素材上传

准备参考素材上传

准备账户所属参考素材上传，取得签名地址及必要上传 header。

接口

POST/api/v1/developer/uploads

鉴权与 Scope

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

Scope: uploads:write

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

使用返回的 method、upload_url 与 required_headers 上传字节；签名上传不附加 API Authorization。随后完成上传，在生成请求中引用 upload_id，而不是 media_id。

相同准备请求的重试复用 Idempotency-Key。签名地址会过期，不要写死示例 URL。

请求参数

字段	类型	必填	说明
`filename`	string	是	文件名。
`media_type`	string	是	受支持 MIME 类型，如 image/png。
`byte_size`	integer	是	正数文件大小，须符合上传及模型限制。
`sha256`	string	否	可用时提供 SHA-256 十六进制校验值。
`role`	string	是	reference_image、start_frame 或 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"}'

响应 HTTP 201

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

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

字段	类型	必填	说明
`upload_id`	UUID	是	账户所属上传标识。
`upload_url / method / required_headers`	string / string / object	是	签名上传说明；严格使用 API 返回值。
`expires_at`	ISO UTC string	是	上传地址过期时间。
`media_type / byte_size / role`	string / integer / string	是	准备上传的文件信息及参考角色。

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

相关错误

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

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

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