Reference uploads

Prepare reference upload

Prepare an owned reference upload and receive the signed target and required upload headers.

Endpoint

POST/api/v1/developer/uploads

Authentication & scope

Authorization: Bearer <credential>; formal account API Key / OAuth only.

Scope: uploads:write

Idempotency-Key — Required; reuse the same value for retries of an identical request.

Use the returned method, upload_url and required_headers to upload bytes; never attach your API Authorization to the signed upload. Then complete the upload and reference its upload_id, not media_id, in a generation request.

Reuse the same Idempotency-Key only for retries of the same prepare request. Signed targets expire; do not hard-code the example URL.

Request parameters

Field	Type	Required	Description
`filename`	string	Yes	File name.
`media_type`	string	Yes	Accepted MIME type, such as image/png.
`byte_size`	integer	Yes	Positive file size, within upload and model limits.
`sha256`	string	No	SHA-256 hex checksum when available.
`role`	string	Yes	reference_image, start_frame or end_frame.

curl --request POST \
  --url 'https://api.perchanceai.art/api/v1/developer/uploads' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'Authorization: Bearer <formal_account_credential>' \
  --header 'Idempotency-Key: <unique_request_uuid>' \
  --header 'Content-Type: application/json' \
  --data '{"filename":"reference.png","media_type":"image/png","byte_size":1024,"role":"reference_image"}'

Response HTTP 201

Illustrative response shape, not a live API response. Example numbers and USD do not imply fixed pricing or a cash balance. Null fields are omitted.

REST success responses contain success, code, message, request_id and data; the table describes data.

Field	Type	Required	Description
`upload_id`	UUID	Yes	Owned upload identifier.
`upload_url / method / required_headers`	string / string / object	Yes	Signed upload instructions; use exactly what the API returns.
`expires_at`	ISO UTC string	Yes	Upload target expiration.
`media_type / byte_size / role`	string / integer / string	Yes	Prepared file and reference role.

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "upload_id": "22222222-2222-4222-8222-222222222222",
    "upload_url": "https://signed-upload.example/upload",
    "method": "PUT",
    "required_headers": {
      "Content-Type": "image/png"
    },
    "expires_at": "2026-10-14T00:10:00.000Z",
    "media_type": "image/png",
    "byte_size": 1024,
    "role": "reference_image"
  }
}

Errors

401 — DEVELOPER_TOKEN_REQUIRED
401 — DEVELOPER_TOKEN_INVALID / DEVELOPER_TOKEN_EXPIRED / DEVELOPER_TOKEN_REVOKED
403 — DEVELOPER_SCOPE_INSUFFICIENT
400 — IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID
413 — UPLOAD_FILE_TOO_LARGE
415 — UPLOAD_TYPE_NOT_ALLOWED
422 — FIELD_REQUIRED / FIELD_INVALID
409 — IDEMPOTENCY_PAYLOAD_MISMATCH / IDEMPOTENCY_IN_PROGRESS / IDEMPOTENCY_REPLAY_EXPIRED

Missing bearer returns REQUIRED; invalid credentials, including historical anonymous tokens, return INVALID. Expired or revoked credentials use their corresponding codes.

{
  "success": false,
  "code": "DEVELOPER_TOKEN_REQUIRED",
  "message": "A developer bearer token is required.",
  "request_id": "docs-example"
}