{"openapi":"3.1.0","info":{"title":"潜行异步生图中转 API","version":"2.3.2","description":"面向客户的潜行异步生图 API。文生图使用 /v1/image-batches/generations，图片编辑与多图合成使用 /v1/image-batches/edits；使用 Bearer API Key 鉴权，提交批次后轮询任务与图片明细。仅按最终成功任务的结果图计费，失败、取消和 unknown 项不扣费。","license":{"name":"UNLICENSED","identifier":"LicenseRef-Proprietary"}},"servers":[{"url":"https://ai-model.qianxingwl.com","description":"潜行生图服务当前部署地址"}],"tags":[{"name":"服务状态","description":"公开健康检查和契约"},{"name":"账户与模型","description":"客户 Bearer API Key 查询接口"},{"name":"异步生图","description":"异步文生图、逐图编辑与多图合成；按每个最终成功任务的结果图收取对应单价"}],"paths":{"/health/live":{"get":{"tags":["服务状态"],"summary":"进程存活检查","operationId":"getLiveness","security":[],"responses":{"200":{"description":"进程存活","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"ok"}}}}}}},"/health/ready":{"get":{"tags":["服务状态"],"summary":"服务就绪检查","description":"检查数据库连接。未就绪时返回 503。","operationId":"getReadiness","security":[],"responses":{"200":{"description":"服务就绪","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"ok","database":"ready"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/openapi.json":{"get":{"tags":["服务状态"],"summary":"下载 OpenAPI 契约","operationId":"getOpenApiDocument","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/models":{"get":{"tags":["账户与模型"],"summary":"查询允许的生图模型","operationId":"listModels","security":[{"BearerApiKey":[]}],"responses":{"200":{"description":"模型列表","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"},"example":{"object":"list","data":[{"id":"gpt-image-2","object":"model","created":0}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"$ref":"#/components/responses/RelayOrUpstreamError"}}}},"/v1/balance":{"get":{"tags":["账户与模型"],"summary":"查询钱包余额","operationId":"getBalance","security":[{"BearerApiKey":[]}],"responses":{"200":{"description":"钱包余额。available = balance - held。","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"},"example":{"object":"balance","currency":"CNY","balance":"100.000000","held":"1.000000","available":"99.000000","active_requests":1}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalOrUpstream"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/usage":{"get":{"tags":["账户与模型"],"summary":"分页查询本用户调用记录","operationId":"listUsage","security":[{"BearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"调用记录","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalOrUpstream"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/image-batches/generations":{"post":{"tags":["异步生图"],"summary":"提交异步文生图批次","description":"⚠️ 在线执行会发起真实请求并产生费用。创建 1-1000 个独立文生图项目并立即返回本中转 batch_id。Idempotency-Key 必填；新批次返回 202，相同 key 和相同请求体重放返回 200。提交时按 n × 文生图单价冻结上限金额，批次终态后仅按 succeeded 图片数扣费，failed、unknown、canceled 项对应金额解除冻结。","operationId":"createImageGenerationBatch","security":[{"BearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/AsyncIdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncImageGenerationRequest"},"example":{"model":"gpt-image-2","prompt":"生成一张未来城市海报，无文字，高清细节","n":1,"size":"2048x1536","quality":"high","response_format":"url"}}}},"responses":{"200":{"$ref":"#/components/responses/AsyncBatchSubmissionReplay"},"202":{"$ref":"#/components/responses/AsyncBatchCreated"},"400":{"$ref":"#/components/responses/BadRequestOrUpstream"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/ForbiddenOrUpstream"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequestsOrUpstream"},"500":{"$ref":"#/components/responses/InternalOrUpstream"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/UpstreamTimeout"},"default":{"$ref":"#/components/responses/RelayOrUpstreamError"}}}},"/v1/image-batches/edits":{"post":{"tags":["异步生图"],"summary":"提交异步图片编辑批次","description":"⚠️ 在线执行会发起真实请求并产生费用。仅 standard 模式支持。images 和 tasks 必须二选一：顶层 images 接受 1-10 张参考图，整组只创建 1 个任务并生成 1 张结果图；tasks 接受 1-1000 个任务，每项可独立设置 model、prompt、images、size、quality 和 response_format，并各生成 1 张结果图。tasks 中省略的公共参数回退到批次顶层；model 和 prompt 必须在任务自身或顶层至少提供一处。逐图处理时每项放 1 张参考图，多图合成时每项可放 1-10 张参考图。Idempotency-Key 必填。计费数量是任务数，不是参考图数量：images 模式冻结 1 个图片编辑单价，tasks 模式冻结 tasks.length × 图片编辑单价。批次终态后仅按 succeeded 任务数扣费，failed、unknown、canceled 项对应金额解除冻结。","operationId":"createMultiImageEditBatch","security":[{"BearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/AsyncIdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncMultiImageEditRequest"},"examples":{"perImageTasks":{"summary":"使用顶层公共参数逐图处理","description":"每个 tasks[i].images 只放 1 张参考图，未在任务中填写的 model、prompt、size、quality 和 response_format 回退到顶层公共参数。","value":{"model":"gpt-image-2","prompt":"保持主体不变，统一调整为高端商业广告效果，无文字","tasks":[{"images":["https://example.com/input-1.png"]},{"images":["https://example.com/input-2.jpg"]}],"size":"2048x1536","quality":"high","response_format":"url"}},"singleTask":{"summary":"单任务多图合成","description":"整个 images 数组属于同一个任务，最终只生成 1 张结果图。","value":{"model":"gpt-image-2","prompt":"融合这些参考图的主体和风格，生成一张统一风格的产品海报，无文字","images":["https://example.com/product.png","https://example.com/background.jpg","https://example.com/style-reference.png"],"size":"2048x1536","quality":"high","response_format":"url"}},"groupedTasks":{"summary":"每项使用完整独立参数","description":"tasks 每项与单任务请求同构，分别携带 model、prompt、images、size、quality 和 response_format；每项独立生成 1 张结果图。","value":{"tasks":[{"model":"gpt-image-2","prompt":"结合商品和场景参考图，生成一张户外广告海报，无文字","images":["https://example.com/task-1-product.png","https://example.com/task-1-background.jpg"],"size":"2048x1536","quality":"high","response_format":"url"},{"model":"gpt-image-2","prompt":"融合人物、服装和风格参考图，生成一张时尚杂志封面，无文字","images":["https://example.com/task-2-product.png","https://example.com/task-2-background.jpg","https://example.com/task-2-style.png"],"size":"1536x2048","quality":"high","response_format":"url"}]}}}}}},"responses":{"200":{"$ref":"#/components/responses/AsyncBatchSubmissionReplay"},"202":{"$ref":"#/components/responses/AsyncBatchCreated"},"400":{"$ref":"#/components/responses/BadRequestOrUpstream"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/ForbiddenOrUpstream"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequestsOrUpstream"},"500":{"$ref":"#/components/responses/InternalOrUpstream"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/UpstreamTimeout"},"default":{"$ref":"#/components/responses/RelayOrUpstreamError"}}}},"/v1/image-batches/{batchId}":{"get":{"tags":["异步生图"],"summary":"查询异步批次总体状态","description":"查询当前用户创建的批次，只读取后台 worker 已持久化的最新状态，不会直接触发一次外部查询。queued、running 等非终态响应会通过 Retry-After 和 X-Poll-Interval-Ms 告知下次允许查询的时间；默认至少间隔 15 秒，并始终以 Retry-After 为准。过早查询返回 429 和 code=poll_rate_limit_exceeded。HTTP 200 只表示成功读取记录；图片结果与最终费用以批次终态和 /items 明细为准。","operationId":"getImageBatch","security":[{"BearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BatchId"}],"responses":{"200":{"description":"批次总体状态","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Poll-Interval-Ms":{"$ref":"#/components/headers/PollIntervalMs"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncImageBatch"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"429":{"$ref":"#/components/responses/TooManyRequestsOrUpstream"},"500":{"$ref":"#/components/responses/InternalOrUpstream"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/UpstreamTimeout"},"default":{"$ref":"#/components/responses/RelayOrUpstreamError"}}}},"/v1/image-batches/{batchId}/items":{"get":{"tags":["异步生图"],"summary":"分页查询异步批次项目明细","description":"分页返回每张图片的状态。批次终态后应读取完整明细；只有 status=succeeded 且 output_url 可用的项目计费，failed、unknown 和 canceled 项不计费并释放对应冻结金额。","operationId":"listImageBatchItems","security":[{"BearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BatchId"},{"$ref":"#/components/parameters/BatchItemLimit"},{"$ref":"#/components/parameters/BatchItemCursor"},{"$ref":"#/components/parameters/BatchItemStatus"}],"responses":{"200":{"description":"批次项目明细","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncBatchItemList"}}}},"400":{"$ref":"#/components/responses/BadRequestOrUpstream"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"500":{"$ref":"#/components/responses/InternalOrUpstream"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/UpstreamTimeout"},"default":{"$ref":"#/components/responses/RelayOrUpstreamError"}}}},"/v1/image-batches/{batchId}/cancel":{"post":{"tags":["异步生图"],"summary":"取消异步批次未开始项目","description":"取消 queued 和 retry_wait 项并释放其对应冻结金额。已经 running 的项目不会被强制中断，仍可能成功并按每张图片计费；调用后应继续查询批次和项目明细。","operationId":"cancelImageBatch","security":[{"BearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BatchId"}],"responses":{"200":{"description":"取消请求后的批次状态","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncImageBatch"}}}},"400":{"$ref":"#/components/responses/BadRequestOrUpstream"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"500":{"$ref":"#/components/responses/InternalOrUpstream"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/UpstreamTimeout"},"default":{"$ref":"#/components/responses/RelayOrUpstreamError"}}}},"/v1/image-batches/{batchId}/retry-failed":{"post":{"tags":["异步生图"],"summary":"重新排队异步批次失败项","description":"仅在批次终态后重新排队 failed 项；unknown、canceled 和已成功项不会重试。本次操作会按重新排队的 failed 项数重新冻结金额，只对重试后新增的成功图片收费。不要自动重试 unknown 项。","operationId":"retryFailedImageBatchItems","security":[{"BearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BatchId"}],"responses":{"200":{"$ref":"#/components/responses/AsyncBatchRetryAccepted"},"400":{"$ref":"#/components/responses/BadRequestOrUpstream"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"429":{"$ref":"#/components/responses/TooManyRequestsOrUpstream"},"500":{"$ref":"#/components/responses/InternalOrUpstream"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/UpstreamTimeout"},"default":{"$ref":"#/components/responses/RelayOrUpstreamError"}}}}},"components":{"headers":{"RequestId":{"description":"服务端调用 ID","schema":{"type":"string","format":"uuid"}},"RetryAfter":{"description":"等待指定秒数后再重试。非终态批次成功响应默认返回 15；本服务的 429 配额拒绝按响应值退避。","schema":{"type":"integer","minimum":1,"examples":[15,60]}},"PollIntervalMs":{"description":"非终态批次建议的客户端轮询间隔（毫秒）；客户端仍应优先遵循 Retry-After。","schema":{"type":"integer","minimum":5000,"examples":[15000]}},"RelayPrice":{"description":"异步批次提交或失败项目重试时冻结的金额上限；最终实扣以成功图片数和 /v1/usage 的 price 为准。金额单位 CNY。","schema":{"$ref":"#/components/schemas/Money"}},"RelayBalance":{"description":"处理后的钱包余额，CNY","schema":{"$ref":"#/components/schemas/Money"}},"IdempotentReplayed":{"description":"是否重放已有结果","schema":{"type":"boolean"}},"RelayBillingStatus":{"description":"异步提交返回 reserved 表示金额已冻结、等待终态结算；pending_or_released 表示提交结果仍待确认或冻结已因明确失败释放，应查询原批次/用量而不要换 Idempotency-Key。","schema":{"type":"string","enum":["reserved","pending_or_released"]}}},"schemas":{"HealthResponse":{"type":"object","required":["status"],"properties":{"status":{"type":"string","const":"ok"},"database":{"type":"string","const":"ready"}},"additionalProperties":true},"ModelList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}},"additionalProperties":false},"Balance":{"type":"object","required":["object","currency","balance","held","available","active_requests"],"properties":{"object":{"type":"string","const":"balance"},"currency":{"type":"string","const":"CNY"},"balance":{"$ref":"#/components/schemas/Money"},"held":{"$ref":"#/components/schemas/Money"},"available":{"$ref":"#/components/schemas/Money"},"active_requests":{"type":"integer","minimum":0,"description":"当前正在执行并占用并发额度的请求数"}},"additionalProperties":false},"UsageList":{"type":"object","required":["object","data","page","page_size","total"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageItem"}},"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0}},"additionalProperties":false},"AsyncImageGenerationRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","minLength":1,"examples":["gpt-image-2"]},"prompt":{"type":"string","minLength":1,"description":"UTF-8 编码后最多 32,768 字节。"},"n":{"type":"integer","minimum":1,"maximum":1000,"default":1,"description":"创建的独立图片项目数，每个项目生成 1 张图；冻结金额为 n × 文生图单价。"},"size":{"type":"string","pattern":"^[1-9]\\d*x[1-9]\\d*$","examples":["1024x1024","2048x1536","3840x2160"]},"quality":{"type":"string","enum":["auto","high"],"default":"auto"},"response_format":{"type":"string","const":"url","default":"url","description":"异步接口只返回 output_url，不支持 b64_json。"}},"additionalProperties":false},"AsyncMultiImageEditRequest":{"description":"异步图片编辑请求，可用于逐图处理、多图合成和分组处理。images 与 tasks 必须严格二选一；参考图数量不是计费数量。","oneOf":[{"$ref":"#/components/schemas/AsyncMultiImageEditSingleRequest"},{"$ref":"#/components/schemas/AsyncMultiImageEditTasksRequest"}]},"AsyncImageBatch":{"type":"object","required":["batch_id","status","total","queued","running","succeeded","failed","unknown","canceled","cancel_requested","created_at","updated_at","poll_url"],"properties":{"batch_id":{"type":"string","minLength":1,"maxLength":128},"status":{"$ref":"#/components/schemas/AsyncBatchStatus"},"model":{"type":"string","description":"批次级公共模型摘要。tasks 使用不同 model，或任务专属配置未形成上游公共摘要时省略。"},"prompt":{"type":"string","description":"批次级公共提示词摘要。tasks 使用不同 prompt，或仅在任务内提供 prompt 时省略。"},"size":{"type":"string"},"quality":{"type":"string","enum":["auto","high"]},"response_format":{"type":"string","const":"url","description":"批次级公共响应格式摘要。tasks 使用任务专属配置且上游未返回公共摘要时省略；异步结果仍只通过项目 output_url 返回。"},"total":{"type":"integer","minimum":1,"maximum":1000},"queued":{"type":"integer","minimum":0},"running":{"type":"integer","minimum":0},"succeeded":{"type":"integer","minimum":0,"description":"最终实际收费图片数。"},"failed":{"type":"integer","minimum":0},"unknown":{"type":"integer","minimum":0,"description":"无法确认上游是否接受的终态项目；不自动重试、不计费。"},"canceled":{"type":"integer","minimum":0},"cancel_requested":{"type":"boolean"},"created_at":{"type":"integer","minimum":0,"description":"Unix 秒级时间戳。"},"updated_at":{"type":"integer","minimum":0,"description":"Unix 秒级时间戳。"},"poll_url":{"type":"string","pattern":"^/v1/image-batches/","description":"本部署的相对查询路径。"}},"additionalProperties":false,"example":{"batch_id":"img_batch_example123","status":"queued","model":"gpt-image-2","prompt":"生成一张未来城市海报，无文字，高清细节","size":"2048x1536","quality":"high","response_format":"url","total":3,"queued":3,"running":0,"succeeded":0,"failed":0,"unknown":0,"canceled":0,"cancel_requested":false,"created_at":1784491200,"updated_at":1784491200,"poll_url":"/v1/image-batches/img_batch_example123"}},"AsyncBatchItemList":{"type":"object","required":["object","data","next_cursor","has_more"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AsyncBatchItem"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"additionalProperties":false},"ErrorResponse":{"type":"object","required":["error","request_id"],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"},"request_id":{"type":"string","format":"uuid"}},"additionalProperties":false},"UpstreamErrorResponse":{"description":"上游错误统一投影为标准错误对象，只保留安全的 message、type、param、code 和本服务 request_id，不返回上游元数据、请求 ID、凭据或身份字段。","allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Model":{"type":"object","required":["id","object","created"],"properties":{"id":{"type":"string","examples":["gpt-image-2"]},"object":{"type":"string","const":"model"},"created":{"type":"integer","minimum":0}},"additionalProperties":false},"Money":{"type":"string","pattern":"^\\d+\\.\\d{6}$","examples":["1.000000"]},"UsageItem":{"type":"object","required":["request_id","operation","model","status","billing_status","mode","price","reserved_price","created_at","completed_at"],"properties":{"request_id":{"type":"string","format":"uuid"},"operation":{"$ref":"#/components/schemas/Operation"},"model":{"type":"string"},"status":{"$ref":"#/components/schemas/RequestStatus"},"billing_status":{"type":"string","enum":["reserved","settled","released"]},"mode":{"type":"string","enum":["sync","async"],"description":"当前请求均为 async，按每张成功图片收费；sync 仅用于展示同步接口禁用前的历史记录。"},"price":{"$ref":"#/components/schemas/Money","description":"实际已扣金额；异步处理中为 0.000000。"},"reserved_price":{"$ref":"#/components/schemas/Money","description":"异步批次提交或失败项目重试时冻结的金额上限；历史 sync 记录保留其禁用前的原冻结金额。"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"AsyncMultiImageEditSingleRequest":{"type":"object","description":"仅 standard 模式支持。顶层 images 中的 1-10 张参考图共同创建 1 个任务，只生成 1 张结果图并最多冻结 1 个图片编辑单价。只接受公网 HTTP(S) URL，不支持 multipart、base64、data URL 或 file_id。","required":["model","prompt","images"],"properties":{"model":{"type":"string","minLength":1,"examples":["gpt-image-2"]},"prompt":{"type":"string","minLength":1,"description":"UTF-8 编码后最多 32,768 字节，应用于该任务的全部参考图。"},"images":{"type":"array","minItems":1,"maxItems":10,"description":"同一个任务的全部参考图；整组固定只输出 1 张图。URL 最长 4096 字符，只允许 HTTP/HTTPS、标准 80/443 端口且不得包含凭据或指向内网/保留地址。","items":{"type":"string","format":"uri","maxLength":4096}},"size":{"type":"string","pattern":"^[1-9]\\d*x[1-9]\\d*$","examples":["1024x1024","2048x1536"]},"quality":{"type":"string","enum":["auto","high"],"default":"auto"},"response_format":{"type":"string","const":"url","default":"url"}},"additionalProperties":false},"AsyncMultiImageEditTasksRequest":{"type":"object","description":"仅 standard 模式支持。tasks 中的每一项是一个独立任务，可使用自己的完整参数并各生成 1 张结果图。顶层 model、prompt、size、quality 和 response_format 是公共回退值，任务自身字段优先；若顶层未提供 model 或 prompt，则每个任务都必须提供对应字段。冻结上限始终为 tasks.length × 图片编辑单价，与参考图数量无关。只接受公网 HTTP(S) URL，不支持 multipart、base64、data URL 或 file_id。","required":["tasks"],"properties":{"model":{"type":"string","minLength":1,"examples":["gpt-image-2"],"description":"tasks 的公共模型回退值；任务自身 model 优先。若省略，所有任务都必须提供 model。"},"prompt":{"type":"string","minLength":1,"description":"tasks 的公共提示词回退值，UTF-8 编码后最多 32,768 字节；任务自身 prompt 优先。若省略，所有任务都必须提供 prompt。"},"tasks":{"type":"array","minItems":1,"maxItems":1000,"description":"批量任务；每项可独立设置完整参数并生成 1 张结果图。计费任务数固定为 tasks.length。","items":{"$ref":"#/components/schemas/AsyncMultiImageEditTask"}},"size":{"type":"string","pattern":"^[1-9]\\d*x[1-9]\\d*$","examples":["1024x1024","2048x1536"],"description":"tasks 的公共尺寸回退值；任务自身 size 优先。"},"quality":{"type":"string","enum":["auto","high"],"default":"auto","description":"tasks 的公共质量回退值；任务自身 quality 优先。"},"response_format":{"type":"string","const":"url","default":"url","description":"tasks 的公共响应格式回退值；任务自身 response_format 优先且只能为 url。"}},"allOf":[{"anyOf":[{"required":["model"]},{"properties":{"tasks":{"items":{"required":["model"]}}}}]},{"anyOf":[{"required":["prompt"]},{"properties":{"tasks":{"items":{"required":["prompt"]}}}}]}],"additionalProperties":false},"AsyncBatchStatus":{"type":"string","enum":["queued","running","succeeded","partially_succeeded","failed","canceled"],"description":"queued/running 为非终态；其余为终态。不要通过计数自行推断终态。"},"AsyncBatchItemStatus":{"type":"string","enum":["queued","running","retry_wait","succeeded","failed","unknown","canceled"],"description":"只有 succeeded 计费；failed、unknown、canceled 不计费并释放对应冻结金额。"},"AsyncBatchItem":{"type":"object","required":["item_id","position","input_url","status","attempt_count","created_at","updated_at"],"properties":{"item_id":{"type":"string","minLength":1},"position":{"type":"integer","minimum":1},"input_url":{"type":"string","description":"纯文生图为空字符串；逐图图生图为对应输入 URL；多图合成时为第一张参考图 URL。"},"input_images":{"type":"array","minItems":1,"maxItems":10,"description":"仅多图合成任务返回，按请求顺序包含该任务使用的全部参考图。","items":{"type":"string","format":"uri","maxLength":4096}},"status":{"$ref":"#/components/schemas/AsyncBatchItemStatus"},"attempt_count":{"type":"integer","minimum":0},"output_url":{"type":["string","null"],"format":"uri","description":"status=succeeded 时读取。"},"http_status":{"type":["integer","null"],"minimum":100,"maximum":599},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"started_at":{"type":["integer","null"],"minimum":0},"finished_at":{"type":["integer","null"],"minimum":0},"created_at":{"type":"integer","minimum":0},"updated_at":{"type":"integer","minimum":0}},"additionalProperties":false},"AsyncBatchRetryResponse":{"type":"object","required":["batch_id","requeued"],"properties":{"batch_id":{"type":"string","minLength":1,"maxLength":128},"requeued":{"type":"integer","minimum":1,"maximum":1000,"description":"本次重新排队并冻结金额的 failed 项数。"}},"additionalProperties":false},"ErrorDetail":{"type":"object","required":["message","type","param","code"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error","server_error"]},"param":{"type":["string","null"]},"code":{"type":"string"},"details":{}},"additionalProperties":false},"Operation":{"type":"string","enum":["image_generation","image_edit"]},"RequestStatus":{"type":"string","enum":["processing","succeeded","failed"]},"AsyncMultiImageEditTask":{"type":"object","description":"一个独立图片编辑任务。可完整设置 model、prompt、images、size、quality 和 response_format；除 images 外，任务未填写的参数回退到批次顶层，任务字段优先。model 和 prompt 必须在任务自身或顶层至少提供一处。","required":["images"],"properties":{"model":{"type":"string","minLength":1,"examples":["gpt-image-2"],"description":"当前任务的模型；省略时回退到顶层 model。"},"prompt":{"type":"string","minLength":1,"description":"当前任务的独立提示词，UTF-8 编码后最多 32,768 字节；省略时回退到顶层 prompt。"},"images":{"type":"array","minItems":1,"maxItems":10,"description":"该任务的全部参考图；每个任务固定只输出 1 张图。","items":{"type":"string","format":"uri","maxLength":4096}},"size":{"type":"string","pattern":"^[1-9]\\d*x[1-9]\\d*$","examples":["1024x1024","2048x1536"],"description":"当前任务的输出尺寸；省略时回退到顶层 size。"},"quality":{"type":"string","enum":["auto","high"],"description":"当前任务的质量；省略时回退到顶层 quality，顶层也省略时默认为 auto。"},"response_format":{"type":"string","const":"url","description":"当前任务的响应格式；只能为 url，省略时回退到顶层 response_format。"}},"additionalProperties":false}},"responses":{"ServiceUnavailable":{"description":"数据库或上游服务暂不可用","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"Unauthorized":{"description":"客户 API Key 缺失、无效、撤销或过期；上游 401 会安全转换为 502","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"UpstreamFailure":{"description":"上游生图响应异常；响应已转换成不含上游元数据的标准错误对象","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpstreamErrorResponse"}}}},"RelayOrUpstreamError":{"description":"其他本服务错误，或已转换成标准错误对象的上游 HTTP 错误","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"InternalOrUpstream":{"description":"本服务内部错误，或上游 500 转换成不含上游元数据的标准错误对象","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"BadRequest":{"description":"请求参数不正确","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AsyncBatchSubmissionReplay":{"description":"相同 Idempotency-Key 和相同请求体的幂等重放，返回原批次，不重复冻结或重复创建任务。原批次仍为非终态时返回 Retry-After 和 X-Poll-Interval-Ms；终态响应可不包含这两个轮询头。","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Image-Relay-Price":{"$ref":"#/components/headers/RelayPrice"},"X-Image-Relay-Balance":{"$ref":"#/components/headers/RelayBalance"},"X-Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"},"X-Image-Relay-Billing-Status":{"$ref":"#/components/headers/RelayBillingStatus"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Poll-Interval-Ms":{"$ref":"#/components/headers/PollIntervalMs"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncImageBatch"}}}},"AsyncBatchCreated":{"description":"新异步批次已创建。保存 batch_id；非终态时至少等待 Retry-After 指定的秒数（默认 15 秒）再使用 poll_url 查询。响应头中的价格是冻结上限，不是最终扣费。","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Image-Relay-Price":{"$ref":"#/components/headers/RelayPrice"},"X-Image-Relay-Balance":{"$ref":"#/components/headers/RelayBalance"},"X-Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"},"X-Image-Relay-Billing-Status":{"$ref":"#/components/headers/RelayBillingStatus"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Poll-Interval-Ms":{"$ref":"#/components/headers/PollIntervalMs"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncImageBatch"}}}},"BadRequestOrUpstream":{"description":"本服务参数错误，或上游 400 转换成不含上游元数据的标准错误对象","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"InsufficientBalance":{"description":"本地可用余额不足，或上游 402 转换成不含上游元数据的标准错误对象","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"ForbiddenOrUpstream":{"description":"本地用户或模型无权访问；上游 403 会安全转换为 502","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"IdempotencyConflict":{"description":"同 key 的原请求仍在处理中、同 key 被用于不同 operation/body 或充值金额、钱包状态冲突，或上游 409 转换成不含上游元数据的标准错误对象","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"UnsupportedMediaType":{"description":"Content-Type 不受支持；异步批次提交只接受 application/json","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequestsOrUpstream":{"description":"本服务拒绝时 code 为 concurrency_limit_exceeded（提交握手并发已满）、rate_limit_exceeded（新提交/失败重试 RPM 已满）、pending_task_limit_exceeded（未完成逻辑任务已满）或 poll_rate_limit_exceeded（批次查询过早），并返回 Retry-After。外部服务的 429 会转换成不含其身份或元数据的标准错误对象。","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]},"examples":{"pendingTaskLimit":{"summary":"未完成逻辑任务达到上限","value":{"error":{"message":"待处理异步任务数已达上限","type":"invalid_request_error","param":null,"code":"pending_task_limit_exceeded","details":{"pending_tasks":100,"requested_tasks":2,"max_pending_tasks":100,"retry_after_seconds":60}},"request_id":"4af92c0b-0c82-4a6b-bc78-cb56277ee768"}},"submissionRateLimit":{"summary":"新提交或失败重试 RPM 达到上限","value":{"error":{"message":"每分钟请求数已达上限","type":"invalid_request_error","param":null,"code":"rate_limit_exceeded","details":{"requests_in_last_minute":60,"requests_per_minute":60,"retry_after_seconds":60}},"request_id":"4af92c0b-0c82-4a6b-bc78-cb56277ee768"}},"submissionConcurrencyLimit":{"summary":"提交握手并发达到上限","value":{"error":{"message":"并发请求数已达上限","type":"invalid_request_error","param":null,"code":"concurrency_limit_exceeded","details":{"active_requests":10,"max_concurrency":10,"retry_after_seconds":60}},"request_id":"4af92c0b-0c82-4a6b-bc78-cb56277ee768"}},"pollRateLimit":{"summary":"批次查询早于允许时间","value":{"error":{"message":"批次状态查询过于频繁，请稍后重试","type":"invalid_request_error","param":null,"code":"poll_rate_limit_exceeded","details":{"retry_after_seconds":15}},"request_id":"4af92c0b-0c82-4a6b-bc78-cb56277ee768"}}}}}},"UpstreamTimeout":{"description":"上游等待超时；响应为不含上游元数据的标准错误对象","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/UpstreamErrorResponse"}]}}}},"NotFound":{"description":"资源不存在","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AsyncBatchRetryAccepted":{"description":"failed 项已重新排队。本次按 requeued × 对应单价冻结上限金额，最终只对重试后新增的 succeeded 图片收费。","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Image-Relay-Price":{"$ref":"#/components/headers/RelayPrice"},"X-Image-Relay-Balance":{"$ref":"#/components/headers/RelayBalance"},"X-Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"},"X-Image-Relay-Billing-Status":{"$ref":"#/components/headers/RelayBillingStatus"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncBatchRetryResponse"}}}}},"parameters":{"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"AsyncIdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"异步批次提交必填，8-128 位字母、数字或 ._:-。相同用户、相同 key 和相同规范化请求体重放时返回原批次，不会重复冻结或重复提交；相同 key 用于不同请求体返回 409。提交超时必须复用原 key 和原请求体，不能换新 key。","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"example":"img-550e8400-e29b-41d4-a716-446655440000"},"BatchId":{"name":"batchId","in":"path","required":true,"description":"异步提交返回的本中转批次 ID，只能由创建它的用户查询和操作。","schema":{"type":"string","minLength":1,"maxLength":128},"example":"img_batch_example123"},"BatchItemLimit":{"name":"limit","in":"query","required":false,"description":"每页项目数。","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},"BatchItemCursor":{"name":"cursor","in":"query","required":false,"description":"上一页返回的 next_cursor；按不透明字符串原样传回。","schema":{"type":"string","minLength":1}},"BatchItemStatus":{"name":"status","in":"query","required":false,"description":"按项目状态过滤。","schema":{"$ref":"#/components/schemas/AsyncBatchItemStatus"}}},"securitySchemes":{"BearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"qxir API key","description":"创建客户 API Key 时一次性返回的 qxir_... 密钥。在 Authorize 中只粘贴完整原始 Key，不要手动添加 Bearer 前缀。"}}}}