生成接口

创建生成任务

使用幂等请求与正式账户积分创建异步图像或视频任务。

接口

POST/api/v1/developer/generations

鉴权与 Scope

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

Scope: generations:write

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

将示例 model_key 和 parameters 替换为当前目录支持的值。拒绝未知字段以及 provider/URL/storage/endpoint 注入。

202 表示接受，不代表完成。不确定的提交使用相同 Idempotency-Key 和相同 payload 重试；新意图使用新 key。持续查询 generation_id 直到终态。

请求参数

字段	类型	必填	说明
`model_key`	string	是	当前公开模型目录返回的完整 key。
`operation`	string	是	image_generation 或 video_generation，必须受所选模型支持。
`prompt`	string	是	非空提示词，最多 8,000 字符。
`negative_prompt`	string	否	最多 8,000 字符，须符合模型支持范围。
`parameters`	object	否	只传该模型 input_schema 接受的参数；按模型要求填写尺寸、时长等。
`reference_upload_ids`	UUID[]	否	已完成上传的 upload_id，最多 8 个；模型限制可能更严格。
`client_trace_id`	string	否	最多 128 字符，仅限 [A-Za-z0-9._:-]+。

curl --request POST \
  --url 'https://api.perchanceai.art/api/v1/developer/generations' \
  --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 '{"model_key":"<model_key_from_catalog>","operation":"image_generation","prompt":"A bright editorial product still life","parameters":{}}'

响应 HTTP 202

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

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

字段	类型	必填	说明
`generation_id`	UUID	是	凭据所属账户及 App 的持久任务标识。
`status`	string	是	持续查询直到 succeeded、failed 或 cancelled；请求被接受不代表完成。
`model_key / modality / operation`	string	是	所选模型、image/video 模态及公开 operation。
`created_at / updated_at`	ISO UTC string	是	UTC 时间。
`completed_at`	ISO UTC string	否	存在时表示完成时间。
`poll_after_ms`	integer	否	非终态建议轮询间隔（当前 2000）；终态省略。
`estimated_credits / reserved_credits / charged_credits`	integer	是	账户积分估价、预扣及实际扣除。
`outputs`	object[]	是	media_id、media_type、url，以及可选 width、height、duration_ms。
`error`	object	否	任务失败信息：code、message、retryable；无错误时省略。
`client_trace_id`	string	否	提供时回传客户端关联标识。

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "generation_id": "11111111-1111-4111-8111-111111111111",
    "status": "queued",
    "model_key": "<model_key_from_catalog>",
    "modality": "image",
    "operation": "image_generation",
    "created_at": "2026-10-14T00:00:00.000Z",
    "updated_at": "2026-10-14T00:00:00.000Z",
    "poll_after_ms": 2000,
    "estimated_credits": 10,
    "reserved_credits": 10,
    "charged_credits": 0,
    "outputs": []
  }
}

创建生成任务

接口

鉴权与 Scope

请求参数

响应 HTTP 202

相关错误