素材上传

完成参考素材上传

完成参考文件上传后，才能在模型输入中使用其 upload_id。

接口

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

鉴权与 Scope

Authorization: Bearer <credential>；仅接受正式账户 API Key / OAuth。

Scope: uploads:write

Idempotency-Key — 必填；相同请求重试复用同一值。

仅在签名字节上传成功后调用。上传须属于当前 App 和凭据 owner。相同完成请求的重试复用 Idempotency-Key。

请求参数

字段	类型	必填	说明
`upload_id`	UUID (path)	是	prepare 返回的标识。
`sha256`	string (body)	否	可选校验值；整个 request body 也可省略。

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>'

响应 HTTP 200

以下为说明响应结构的示例，并非实时 API 响应。示例数值和 USD 不代表固定定价或资金余额。空字段省略。

REST 成功响应为 success、code、message、request_id 和 data；下表描述 data。

字段	类型	必填	说明
`upload_id / media_id`	UUID	是	reference_upload_ids 使用 upload_id；media_id 是账户媒体标识。
`status / media_type / byte_size`	string / string / integer	是	ready 状态及完成后的媒体信息。

{
  "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
  }
}

相关错误

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

缺 bearer 返回 REQUIRED；无效凭据（包括历史匿名令牌）返回 INVALID。过期或撤销凭据使用对应错误码。

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