Reference uploads

Complete reference upload

Complete an uploaded reference file before using its upload_id in model input.

Endpoint

POST/api/v1/developer/uploads/{upload_id}/complete

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.

Call only after the signed byte upload succeeds. The upload must belong to this App and credential owner. Keep the same Idempotency-Key for identical completion retries.

Request parameters

Field	Type	Required	Description
`upload_id`	UUID (path)	Yes	Identifier returned by prepare.
`sha256`	string (body)	No	Optional checksum; the entire request body is optional.

curl --request POST \
  --url 'https://api.perchanceai.art/api/v1/developer/uploads/{upload_id}/complete' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'Authorization: Bearer <formal_account_credential>' \
  --header 'Idempotency-Key: <unique_request_uuid>'

Response HTTP 200

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 / media_id`	UUID	Yes	Use upload_id for reference_upload_ids; media_id is the owned media identity.
`status / media_type / byte_size`	string / string / integer	Yes	Ready state and completed media properties.

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "upload_id": "22222222-2222-4222-8222-222222222222",
    "media_id": "33333333-3333-4333-8333-333333333333",
    "status": "ready",
    "media_type": "image",
    "byte_size": 1024
  }
}

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
410 — UPLOAD_URL_EXPIRED
422 — 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"
}