{ "openapi": "3.1.0", "info": { "title": "ClipmivoAI API", "version": "0.2.0", "description": "Public workflow API and CLI contract. Production acceptance remains incomplete. Callback delivery, external URL import and R2 presigned uploads are not yet supported. No payment operations. / 公开工作流 API 与 CLI 合约；生产整体验收尚未完成。签名回调、外链导入、R2预签名直传仍待实现，不包含支付。" }, "servers": [ { "url": "https://clipmivoai.com/api/open/v1" } ], "security": [ { "ApiKey": [] } ], "externalDocs": { "url": "https://clipmivoai.com/?section=api&lang=en", "description": "Developer workspace / 开发者工作台" }, "paths": { "/callbacks": { "get": { "operationId": "listCallbacks", "summary": "List owned endpoints / 本账户回调端点", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/CallbackEndpoint" } }, "ready": { "type": "boolean" } }, "required": [ "endpoints", "ready" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createCallback", "summary": "Register endpoint; secret returned once / 注册端点并一次性返回密钥", "x-required-key-scope": "video:write", "responses": { "201": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string" }, "verified": { "const": false } }, "required": [ "id", "url", "secret", "verified" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url" ], "additionalProperties": false } } } }, "description": "Requires operator-enabled callbacks and an allowed public HTTPS host. Maximum five active endpoints per owner. / 需要运营端启用回调并允许目标HTTPS主机，每个账户最多五个有效端点。" } }, "/callbacks/{endpoint_id}": { "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "delete": { "operationId": "disableCallback", "summary": "Disable endpoint / 停用端点", "x-required-key-scope": "video:write", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "disabled": { "const": true } }, "required": [ "disabled" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/callbacks/{endpoint_id}/verify": { "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "post": { "operationId": "verifyCallback", "summary": "Verify signed challenge / 验证签名挑战", "x-required-key-scope": "video:write", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "verified": { "const": true } }, "required": [ "id", "verified" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Receiver must verify the signed endpoint.verification JSON and return its challenge as the exact plain response body within ten seconds. / 接收方验签后须在十秒内原样返回challenge字符串。" } }, "/callbacks/{endpoint_id}/deliveries": { "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "listCallbackDeliveries", "summary": "Latest delivery records / 最近投递记录", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/CallbackDelivery" } }, "limit": { "const": 100 } }, "required": [ "deliveries", "limit" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/callbacks/{endpoint_id}/deliveries/{delivery_id}/retry": { "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "post": { "operationId": "retryCallbackDelivery", "summary": "Retry failed delivery / 重试失败投递", "x-required-key-scope": "video:write", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "const": "pending" } }, "required": [ "id", "state" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Only failed deliveries at least 30 seconds old can be retried. Keeps event ID/body; never resubmits a video. / 仅可重试失败至少30秒的投递，保留事件ID和内容，不重新生成视频。" } }, "/models": { "get": { "operationId": "listModels", "summary": "List workflow profiles / 模型能力目录", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "readiness": { "type": "object" } }, "required": [ "models" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Account task usage and current-key calls / 账号任务用量与当前密钥调用次数", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "as_of": { "type": "integer" }, "period": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "time_basis": { "const": "task_created_at" }, "end_exclusive": { "const": true } }, "required": [ "from", "to", "time_basis", "end_exclusive" ] }, "account_tasks": { "type": "object", "properties": { "scope": { "const": "account" }, "excludes": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" }, "by_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "credits_settled": { "type": "integer" } }, "required": [ "scope", "excludes", "count", "by_status", "credits_settled" ] }, "current_key": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "calls_total": { "type": "integer" }, "last_used": { "type": [ "integer", "null" ] } }, "required": [ "id", "calls_total", "last_used" ] }, { "type": "null" } ] } }, "required": [ "as_of", "period", "account_tasks", "current_key" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Account-wide retained, non-draft tasks selected by creation time, not per-key billing or settlement date. Deleted tasks are excluded. Current-key calls are lifetime counters including this call and permitted requests that later fail; invalid-key/scope failures are excluded. Non-atomic snapshot. / 按创建时间统计账号保留的非草稿任务，非按密钥账单或结算日期。排除已删除任务。当前密钥调用数为累计值，含本次及权限通过后失败的请求，不含无效密钥或权限失败。非原子快照。", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Inclusive Unix seconds; defaults to 30 days before to. / 含起点，Unix 秒，默认结束前30天。" }, { "name": "to", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Exclusive Unix seconds, no later than current second + 1; range at most 31 days. / 不含终点，最多当前秒+1，区间不超过31天。" } ] } }, "/credits/balance": { "get": { "operationId": "getBalance", "summary": "Credit balance / 点数余额", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "description": "Current ClipmivoAI credit balance and usage restrictions. / 当前 ClipmivoAI 点数余额及使用限制。" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/generations/quote": { "post": { "operationId": "quoteGeneration", "summary": "Quote without submitting / 只报价不提交", "x-required-key-scope": "video:create or video:write", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "credits_to_hold": { "type": "number" }, "currency": { "const": "credits" } }, "required": [ "credits_to_hold", "currency" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRequest" } } } } } }, "/videos/generations": { "post": { "operationId": "createGeneration", "summary": "Create once using an idempotency key / 使用幂等键提交", "x-required-key-scope": "video:create or video:write", "responses": { "202": { "description": "Accepted, not completed / 已接收，尚未完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Reuse the same key and body after a lost response. Never auto-resubmit with a new key. / 丢失响应后使用同一键和请求重试。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRequest" } } } } }, "get": { "operationId": "listGenerations", "summary": "List owned tasks / 本账户任务列表", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "tasks", "next_cursor" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor from the preceding page / 上一页返回的游标" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "queued", "submitting", "processing", "succeeded", "failed", "needs_review" ] }, "description": "Compatibility listings never expose drafts. / 兼容接口不返回草稿。" } ] } }, "/videos/generations/{task_id}": { "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "getGeneration", "summary": "Read owned task / 查询本账户任务", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/generations/{task_id}/download": { "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "downloadGeneration", "summary": "Download stored output / 下载已入库成片", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Authenticated file / 需认证的文件", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial file bytes / 分段文件内容", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Range", "in": "header", "schema": { "type": "string" } }, { "name": "download", "in": "query", "schema": { "type": "string", "enum": [ "1" ] } } ] } }, "/uploads": { "post": { "operationId": "reserveUpload", "summary": "Reserve an authenticated upload / 预留上传", "x-required-key-scope": "files:write", "responses": { "201": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/UploadReservation" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } } } } }, "/uploads/{upload_id}": { "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "getUploadStatus", "summary": "Check an owned upload after a lost response / 查询上传状态以恢复丢失的响应", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/UploadStatus" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "uploadBytes", "summary": "Upload raw bytes for the same owner / 同账户上传原始文件", "x-required-key-scope": "files:write", "responses": { "201": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Asset" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "X-Upload-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Content-Length", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 52428800 } } ], "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/bmp": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } }, "audio/mp4": { "schema": { "type": "string", "format": "binary" } }, "audio/webm": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/x-wav": { "schema": { "type": "string", "format": "binary" } } } }, "description": "Use the returned path under this API prefix, same owner, token, MIME and exact byte count. Completed token replay returns the existing asset. 10-minute credential; this is authenticated Worker streaming, not R2 presigned upload. / 使用预留返回的路径、相同账户、令牌、类型和字节数。完成后的令牌重放返回原素材；凭证有效期10分钟。" } }, "/uploads/{upload_id}/parts/{index}": { "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 16 } } ], "put": { "operationId": "uploadPart", "summary": "Upload a bounded file part / 上传文件分片", "x-required-key-scope": "files:write", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "received": { "type": "boolean" }, "index": { "type": "integer" } }, "required": [ "received" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "X-Upload-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "description": "Files above 3 MiB must use numbered parts: 3,145,728 bytes each, except the final remainder. Send exact Content-Length, the same owner and reservation token. Then POST complete. / 大于3 MiB的文件使用从0编号的分片，每片3145728字节，最后一片为剩余字节；保持相同账户和上传令牌，最后调用complete。" } }, "/uploads/{upload_id}/complete": { "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "post": { "operationId": "completeUploadParts", "summary": "Validate and complete a multipart upload / 校验并完成分片上传", "x-required-key-scope": "files:write", "responses": { "201": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Asset" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "X-Upload-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "description": "Send no body. All parts must already exist; original MIME, size, quota and media checks still apply. / 无请求体；所有分片必须已上传，原文件类型、大小、配额和媒体校验保持不变。" } }, "/assets": { "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 }, "description": "Page size / 每页数量" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Use next_cursor from the previous response / 使用上次响应的 next_cursor" } ], "get": { "operationId": "listAssets", "summary": "List owned assets / 素材列表", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "assets", "next_cursor" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{asset_id}/file": { "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "readAssetFile", "summary": "Read private media / 读取私有素材", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Authenticated file / 需认证的文件", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial file bytes / 分段文件内容", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Range", "in": "header", "schema": { "type": "string" } } ] } }, "/assets/{asset_id}": { "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "getAsset", "summary": "Read owned asset / 查看本人素材", "x-required-key-scope": "video:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Asset" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "renameAsset", "summary": "Rename owned asset / 重命名本人素材", "x-required-key-scope": "files:write", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "updated": { "const": true } }, "required": [ "updated" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] } } } } }, "delete": { "operationId": "deleteAsset", "summary": "Remove owned asset and queue file cleanup / 移除本人素材并排队清理文件", "x-required-key-scope": "files:write", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "deleted": { "const": true } }, "required": [ "deleted" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/images/models": { "get": { "operationId": "imageModels", "summary": "Discover only enabled, verified image profiles", "x-required-key-scope": "image:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ratios": { "type": "array", "items": { "type": "string" } }, "resolutions": { "type": "array", "items": { "type": "string" } }, "qualities": { "type": "array", "items": { "type": "string" } }, "maxReferences": { "type": "integer" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "ratio": { "type": "string" }, "resolution": { "type": "string" }, "quality": { "type": "string" }, "reference": { "type": "boolean" }, "credits": { "type": "integer" } }, "required": [ "ratio", "resolution", "quality", "reference", "credits" ] } } }, "required": [ "id", "profiles" ] } } }, "required": [ "enabled", "models" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/images/quote": { "post": { "operationId": "quoteImage", "summary": "Quote supported settings before creating a task", "x-required-key-scope": "image:write", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "credits": { "type": "integer" }, "estimated": { "type": "boolean" } }, "required": [ "credits", "estimated" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageSettings" } } } } } }, "/images/jobs": { "get": { "operationId": "listImageJobs", "summary": "Latest 30 owned image tasks, newest first", "x-required-key-scope": "image:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/ImageJob" } } }, "required": [ "tasks" ] } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createImageJob", "summary": "Reserve credits and submit one image; at most two unsettled tasks per account", "x-required-key-scope": "image:write", "responses": { "202": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/ImageJob" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,100}$" }, "description": "Reuse with identical settings on retries; changed settings return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/ImageSettings" }, "quoted_credits": { "type": "integer", "minimum": 1 } }, "required": [ "settings", "quoted_credits" ] } } } } } }, "/images/jobs/{job_id}": { "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "getImageJob", "summary": "Poll owned image task; needs_review is not a refund or failure", "x-required-key-scope": "image:read", "responses": { "200": { "description": "Success / 成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/ImageJob" } }, "required": [ "success", "request_id", "data" ] } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/images/jobs/{job_id}/file": { "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "get": { "operationId": "downloadImage", "summary": "Download private generated image; 409 before success, 404 if removed", "x-required-key-scope": "image:read", "responses": { "200": { "description": "Private PNG, JPEG or WebP bytes", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "operationId": "headImage", "summary": "Read generated file headers", "x-required-key-scope": "image:read", "responses": { "200": { "description": "Private image headers" }, "400": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected / 请求被拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ff_…", "description": "Obtain a scoped key in the authenticated Developer area. / 登录开发者页面创建具备相应权限的密钥。" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "const": false }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "success", "error" ] }, "Model": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string" }, "verification": { "type": "string" }, "billing_verified": { "type": "boolean" }, "durations": { "type": "array", "items": { "type": "integer" } }, "qualities": { "type": "array", "items": { "type": "string" } }, "aspect_ratios": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "object" } }, "required": [ "id", "mode", "verification", "billing_verified" ] }, "GenerationRequest": { "type": "object", "properties": { "model": { "type": "string", "description": "Exact workflow ID from GET models; supported fields vary by model. / 使用模型目录中的完整工作流ID。" }, "prompt": { "type": "string", "maxLength": 10000 }, "duration": { "type": "number", "description": "Use the selected model/mode/quality duration list. / 按对应模型和清晰度选择。" }, "quality": { "type": "string" }, "aspect_ratio": { "type": "string" }, "generate_audio": { "type": "boolean" }, "image_urls": { "type": "array", "items": { "type": "string", "maxLength": 2048 } }, "video_urls": { "type": "array", "items": { "type": "string", "maxLength": 2048 } }, "audio_urls": { "type": "array", "items": { "type": "string", "maxLength": 2048 } }, "metadata": { "type": "object", "maxProperties": 16, "additionalProperties": { "type": "string" } }, "quoted_credits": { "type": "number" }, "callback_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Exact URL of a verified endpoint owned by this account; requires a healthy callback worker. / 本账户已验证端点地址，需要回调后台正常运行。" }, "seed": { "type": "integer" }, "negative_prompt": { "type": "string" }, "watermark": { "type": "boolean" }, "edit_audio": { "type": "string", "enum": [ "auto", "origin" ] }, "media_roles": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "model" ], "additionalProperties": false, "description": "Media URLs must resolve to same-origin owned assets. Callbacks require registration, verification and enabled dispatch; hosted acceptance is pending. Defaults vary by model. / 媒体URL须对应同源本人素材；回调需先注册、验证并启用调度，线上验收待完成。默认值因模型而异。" }, "CallbackEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "verified": { "type": "boolean" }, "disabled": { "type": "boolean" }, "created": { "type": "integer" } }, "required": [ "id", "url", "verified", "disabled", "created" ] }, "CallbackDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "delivering", "delivered", "failed", "cancelled" ] }, "attempts": { "type": "integer" }, "next_attempt": { "type": "integer" }, "http_status": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "created": { "type": "integer" }, "updated": { "type": "integer" } }, "required": [ "id", "event", "state", "attempts", "next_attempt", "http_status", "error", "created", "updated" ] }, "Task": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "video.generation.task" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "needs_review" ] }, "created": { "type": "integer" }, "task_info": { "type": "object", "properties": { "can_cancel": { "const": false }, "needs_review": { "type": "boolean" } }, "required": [] }, "usage": { "type": "object", "properties": { "billing_rule": { "type": "string", "enum": [ "total_tokens", "quoted_credits" ], "description": "Settlement basis, not a per-second guarantee. / 结算依据，不表示按秒收费。" }, "credits_reserved": { "type": "integer", "minimum": 0, "description": "Original reservation before settlement. / 结算前的原始预留点数。" }, "credits_settled": { "type": "integer", "minimum": 0, "description": "Final charge after successful settlement. / 成功结算后的实际扣除点数。" }, "credits_refunded": { "type": "integer", "minimum": 0, "description": "Credits returned to original lots, which retain their expiry and restrictions. / 退回原点数批次，保留其有效期及限制。" } }, "required": [ "billing_rule", "credits_reserved", "credits_settled", "credits_refunded" ] }, "result": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "download_url": { "type": "string" }, "requires_authentication": { "const": true } }, "required": [ "download_url", "requires_authentication" ] } ] }, "error": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "object", "model", "status", "created", "task_info", "usage", "result", "error", "metadata" ] }, "UploadRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "mime": { "type": "string" }, "size": { "type": "integer", "minimum": 1, "maximum": 52428800 }, "duration": { "type": "number", "minimum": 0 }, "character": { "type": "boolean" }, "consent": { "type": "boolean" } }, "required": [ "name", "mime", "size" ], "description": "Duration is required for audio/video and declared by the client. Character assets require explicit consent. / 音视频需客户端声明时长，角色素材需明确同意。" }, "UploadStatus": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "reserved", "uploading", "complete", "failed", "expired" ] }, "expires": { "type": "integer" }, "asset": { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "type": "null" } ] } }, "required": [ "id", "status", "expires", "asset" ] }, "UploadReservation": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "token": { "type": "string" }, "expires": { "type": "integer" }, "method": { "const": "PUT" } }, "required": [ "id", "path", "token", "expires", "method" ] }, "Asset": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "character" ] }, "mime": { "type": "string" }, "size": { "type": "integer" }, "duration": { "type": "number" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "created": { "type": "integer" }, "url": { "type": "string" } }, "required": [ "id", "name", "kind", "mime", "size", "duration", "url" ] }, "ImageSettings": { "type": "object", "properties": { "model": { "type": "string" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "ratio": { "type": "string" }, "resolution": { "type": "string" }, "quality": { "type": "string" }, "asset_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "model", "prompt", "ratio", "resolution", "quality", "asset_ids" ] }, "ImageJob": { "type": "object", "properties": { "id": { "type": "string" }, "settings": { "$ref": "#/components/schemas/ImageSettings" }, "status": { "type": "string", "enum": [ "queued", "submitting", "processing", "needs_review", "succeeded", "failed" ] }, "held_credits": { "type": "integer" }, "consumed_credits": { "type": [ "integer", "null" ] }, "refunded_credits": { "type": "integer" }, "asset_id": { "type": [ "string", "null" ] }, "output_url": { "type": [ "string", "null" ], "description": "Relative authenticated file URL; requires image:read. Null until persisted." }, "error": { "type": [ "string", "null" ] }, "created": { "type": "integer" }, "updated": { "type": "integer" } }, "required": [ "id", "settings", "status", "held_credits", "consumed_credits", "refunded_credits", "asset_id", "output_url" ] } } } }