{ "openapi": "3.1.0", "info": { "title": "Creative Reasoning Router — 模型服务 API", "version": "2.0.0", "description": "使用 CR API 调用 LLM、Embedding、Rerank、图像和视频模型，并查询异步任务。各接口列出请求字段、响应和错误。\n\n使用 `Authorization: Bearer ` 认证。API Base URL 显示在本页，API Key 在 CR 控制台创建。可调用的模型由 API Key 权限决定；[模型目录](/models)列出模型和公开价格。\n\n本页只展示契约和示例，不会发送请求。" }, "servers": [ { "url": "https://api.creative-reasoning.com", "description": "CR 模型 API" } ], "tags": [ { "name": "LLM", "description": "LLM 文本、Responses、Embedding 与 Rerank。" }, { "name": "Image", "description": "图像生成、编辑与任务轮询。" }, { "name": "Video", "description": "视频任务提交、回调与轮询。" }, { "name": "Assets", "description": "独立素材上传、元数据查询和删除。" }, { "name": "Media tasks", "description": "图片与视频共用的任务查询和等待。" }, { "name": "Metering", "description": "独立计量接口；普通模型接入通常不需要。" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/unified/v1/chat/completions": { "post": { "tags": [ "LLM" ], "summary": "对话补全", "description": "兼容 OpenAI 的对话补全。当 `stream` 为 `true` 时，响应为 `text/event-stream` 的服务器发送事件（SSE），以 `data: [DONE]` 结束，最终的用量块位于其之前；否则返回单个 JSON `ChatCompletionResponse`。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "补全结果。非流式为 JSON；`stream=true` 时为 SSE 流。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "服务器发送事件：每条 `data:` 行携带一个对话补全块；流以 `data: [DONE]` 结束。" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "502": { "$ref": "#/components/responses/ModelServiceError" }, "503": { "$ref": "#/components/responses/Overloaded" } }, "operationId": "createUnifiedV1ChatCompletions" } }, "/unified/v1/responses": { "post": { "tags": [ "LLM" ], "summary": "Responses API", "description": "OpenAI Responses API。将上一次 CR 响应中的 ID 填入 `previous_response_id` 可继续对话；该 ID 仅在原 API Key 的权限范围内有效。设置 `stream=true` 可获得 SSE 事件流。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRequest" } } } }, "responses": { "200": { "description": "响应对象。非流式为 JSON；`stream=true` 时为 SSE 流。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseObject" } }, "text/event-stream": { "schema": { "type": "string", "description": "响应增量的服务器发送事件。" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "模型未找到，或 `previous_response_id` 未找到/已过期。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "502": { "$ref": "#/components/responses/ModelServiceError" }, "503": { "$ref": "#/components/responses/Overloaded" } }, "operationId": "createUnifiedV1Responses" } }, "/unified/v1/models": { "get": { "tags": [ "LLM" ], "summary": "列出可访问的模型", "description": "使用 API Key 获取已上架、已启用、有可用路由且当前访问策略允许的文本生成模型，包含接受图片等多模态输入的文本模型。兼容地址为 `GET /v1/models`。此操作不产生推理用量或费用。`context_window`、`context_length` 和 `max_output_tokens` 是 CR 扩展字段；已知的正整数上限才会返回，未知时省略。`context_length` 与 `context_window` 相同。客户端需要支持这些扩展字段才能使用上限；部分 agent 仍需手动配置。列表不表示实时健康状态，也不保证请求成功。\n\n默认返回文本模型。指定 capability=portrait_assets 时，返回当前 API Key 可访问、已上架且已配置可用人像素材渠道的模型；使用返回的 id 作为素材上传的 model。该筛选不返回文本上下文上限。\n\n使用 capability=image_outpaint 查询有权限、已发布且具有已验证兼容路由的扩图模型。data[].capabilities.image_outpaint 返回比例步长、边界、单张输出及输入约束。", "operationId": "listUnifiedV1Models", "responses": { "200": { "description": "当前 API Key 按指定能力可发现的模型；未指定时返回文本模型。", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Vary": { "schema": { "type": "string" }, "example": "Authorization" }, "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" }, "example": { "object": "list", "data": [ { "id": "YOUR_MODEL", "object": "model", "created": 1789344000, "owned_by": "cr", "context_window": 262144, "context_length": 262144, "max_output_tokens": 32768 }, { "id": "ANOTHER_MODEL", "object": "model", "created": 1789344000, "owned_by": "cr" } ] } } } }, "400": { "description": "capability 非法或重复。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "模型列表暂时无法读取。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "capability", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "portrait_assets", "image_outpaint" ] }, "description": "默认返回文本模型。指定 capability=portrait_assets 时，返回当前 API Key 可访问、已上架且已配置可用人像素材渠道的模型；使用返回的 id 作为素材上传的 model。该筛选不返回文本上下文上限。使用 capability=image_outpaint 查询有权限、已发布且具有已验证兼容路由的扩图模型。data[].capabilities.image_outpaint 返回比例步长、边界、单张输出及输入约束。" } ] } }, "/unified/v1/embeddings": { "post": { "tags": [ "LLM" ], "summary": "向量嵌入", "description": "为文本、文本数组或多模态输入数组生成嵌入向量。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" } } } }, "responses": { "200": { "description": "嵌入向量。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "502": { "$ref": "#/components/responses/ModelServiceError" }, "503": { "$ref": "#/components/responses/Overloaded" } }, "operationId": "createUnifiedV1Embeddings" } }, "/unified/v1/rerank": { "post": { "tags": [ "LLM" ], "summary": "重排序", "description": "按相关性对一组文档相对于查询进行重排序。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" } } } }, "responses": { "200": { "description": "排序结果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "502": { "$ref": "#/components/responses/ModelServiceError" }, "503": { "$ref": "#/components/responses/Overloaded" } }, "operationId": "createUnifiedV1Rerank" } }, "/unified/v1/images/tasks": { "post": { "tags": [ "Image" ], "summary": "异步图片任务（推荐）", "operationId": "createUnifiedV1ImageTask", "description": "受理并保存任务后返回 202，不等待生成。始终返回 CR 任务，不受 callback_url 影响。生成参数沿用对应生成/JSON 编辑接口；callback_url 仅用于终态通知，正文与终态查询结果一致。新接口不接受 response_mode。", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "建议提供。1–256 个非空白可打印 ASCII 字符。同一 API Key、同一操作、同一接口和相同请求复用任务。参数变更返回 409。任务记录保留 30 天。", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageGenerationRequest" }, { "not": { "required": [ "response_mode" ] } } ] } } } }, "responses": { "200": { "description": "重复 POST：同一任务已完成，仍返回任务对象。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTaskResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "202": { "description": "任务已受理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTaskResponse" } } }, "headers": { "Location": { "schema": { "type": "string" }, "description": "任务查询路径。" }, "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "任务结果已过期；不会重新创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "task_capacity_exceeded：此 API Key 已有 128 个未完成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "task_unavailable：任务受理暂时不可用。错误或响应丢失不能证明未受理；以同一幂等键和请求重试。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "callbacks": { "imageTerminal": { "$ref": "#/components/callbacks/CrImageTerminal" } } } }, "/unified/v1/images/edit-tasks": { "post": { "tags": [ "Image" ], "summary": "异步图片编辑任务（推荐）", "operationId": "createUnifiedV1ImageEditTask", "description": "受理并保存任务后返回 202，不等待生成。始终返回 CR 任务，不受 callback_url 影响。生成参数沿用对应生成/JSON 编辑接口；callback_url 仅用于终态通知，正文与终态查询结果一致。新接口不接受 response_mode。\n\n扩图模型使用 ImageOutpaintRequest：model 固定操作，expansion 只传四向比例。普通图片模型收到 expansion 返回 400 unsupported_image_operation。多个操作参数组（即使值为 null）返回 conflicting_image_operations。超分和去背景参数当前不受支持。扩图必须使用本操作的请求结构和入口。", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "建议提供。1–256 个非空白可打印 ASCII 字符。同一 API Key、同一操作、同一接口和相同请求复用任务。参数变更返回 409。任务记录保留 30 天。", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageGenerationRequest" }, { "not": { "required": [ "response_mode" ] } } ] }, { "$ref": "#/components/schemas/ImageOutpaintRequest" } ] } } } }, "responses": { "200": { "description": "重复 POST：同一任务已完成，仍返回任务对象。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTaskResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "202": { "description": "任务已受理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTaskResponse" } } }, "headers": { "Location": { "schema": { "type": "string" }, "description": "任务查询路径。" }, "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "任务结果已过期；不会重新创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "task_capacity_exceeded：此 API Key 已有 128 个未完成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "task_unavailable：任务受理暂时不可用。错误或响应丢失不能证明未受理；以同一幂等键和请求重试。 invalid_image_contract 表示模型配置不可用；no_compatible_route 表示没有已验证的兼容路由，联系管理员。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "callbacks": { "imageTerminal": { "$ref": "#/components/callbacks/CrImageTerminal" } } } }, "/unified/v1/videos/tasks": { "post": { "tags": [ "Video" ], "summary": "异步视频任务（推荐）", "operationId": "createUnifiedV1VideoTask", "description": "受理并保存任务后返回 202，不等待生成。始终返回 CR 任务，不受 callback_url 影响。生成参数沿用对应生成/JSON 编辑接口；callback_url 仅用于终态通知，正文与终态查询结果一致。新接口不接受 response_mode。", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "建议提供。1–256 个非空白可打印 ASCII 字符。同一 API Key、同一操作、同一接口和相同请求复用任务。参数变更返回 409。任务记录保留 30 天。", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/VideoGenerationRequest" }, { "not": { "required": [ "response_mode" ] } } ] } } } }, "responses": { "200": { "description": "重复 POST：同一任务已完成，仍返回任务对象。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTaskResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "202": { "description": "任务已受理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTaskResponse" } } }, "headers": { "Location": { "schema": { "type": "string" }, "description": "任务查询路径。" }, "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "任务结果已过期；不会重新创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "task_capacity_exceeded：此 API Key 已有 128 个未完成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "task_unavailable：任务受理暂时不可用。错误或响应丢失不能证明未受理；以同一幂等键和请求重试。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "callbacks": { "videoTerminal": { "{$request.body#/callback_url}": { "post": { "summary": "接收视频终态回调", "description": "仅当请求包含 `callback_url` 时发送。正文是状态为 `completed` 或 `failed` 的 CR 视频任务响应。重试使用相同正文。接收方按任务 `id` 去重，持久化结果后返回任意 2xx。", "security": [], "parameters": [ { "name": "user-agent", "in": "header", "required": true, "description": "固定为 `CR-Webhook/1.0`。", "schema": { "type": "string", "const": "CR-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrVideoTerminalCallback" } } } }, "responses": { "2XX": { "description": "接收方已持久化或已处理该任务 `id`。" } } } } } } } }, "/unified/v1/tasks/{task_id}": { "get": { "tags": [ "Media tasks" ], "operationId": "getUnifiedV1MediaTask", "summary": "查询媒体任务", "description": "使用提交时的同一 API Key，只读已有任务，不重复生成或扣费。终态结果保留 24 小时，之后返回 410。", "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "任务当前状态。生成失败也返回 200，status 为 failed。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTaskResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "任务不存在或不属于此 API Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "结果已过期。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "任务状态暂时无法读取。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/unified/v1/tasks/{task_id}/wait": { "get": { "tags": [ "Media tasks" ], "operationId": "waitUnifiedV1MediaTask", "summary": "等待媒体任务", "description": "使用提交时的同一 API Key，只读已有任务，不重复生成或扣费。最多等 30 秒；未完成也返回 200 和当前状态，不取消任务。终态结果保留 24 小时，之后返回 410。", "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "任务当前状态。生成失败也返回 200，status 为 failed。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTaskResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "任务不存在或不属于此 API Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "结果已过期。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "等待连接已达上限，请普通查询。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "任务状态暂时无法读取。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/unified/v1/images/generations": { "post": { "tags": [ "Image" ], "summary": "提交图像生成", "description": "旧接口继续兼容，尚未废弃。新接入推荐 POST /unified/v1/images/tasks；详见[异步媒体任务](/docs/zh/media-tasks)。\n\n提交图像生成请求。同步响应可直接返回 `data`，且不一定包含 `id` 或 `status`；异步响应返回 `pending`/`processing` 任务，通过 `GET /unified/v1/images/generations/{task_id}` 轮询。\n\n顶层 callback_url 可用于图像生成和 JSON 编辑。携带该字段时，成功提交返回 CR id、pending 状态和 poll_url，CR 仅投递 completed 或 failed 终态，正文与终态 GET 响应逐字节一致。同步模型仍需等待本次生成结束，结果保存后由后台投递，不会再次生成。不传 callback_url 时保持原有同步或异步响应。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" } } } }, "responses": { "200": { "description": "图像生成结果，或已受理的异步任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "description": "请求无效。回调地址无效时返回 invalid_callback_url；provider_options 内的 callback_url 返回 reserved_parameter。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "502": { "$ref": "#/components/responses/ModelServiceError" }, "503": { "description": "回调配置或持久化不可用时返回 callback_unavailable。模型服务已接受但结果保存失败时也可能返回此错误，不应盲目重复提交。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "createUnifiedV1ImagesGenerations", "callbacks": { "imageTerminal": { "$ref": "#/components/callbacks/CrImageTerminal" } } } }, "/unified/v1/images/edits": { "post": { "tags": [ "Image" ], "summary": "提交图像编辑", "description": "旧接口继续兼容，尚未废弃。新接入推荐 POST /unified/v1/images/edit-tasks；详见[异步媒体任务](/docs/zh/media-tasks)。\n\n使用统一 JSON 接口编辑图像，与图像生成共用请求和响应结构。通过 `image` 传入参考素材；图像格式、数组及 `mask` 的支持取决于所选模型。本接口不接收 multipart 上传。同步响应直接包含 `data`，且不一定包含 `id` 或 `status`；异步任务通过 `GET /unified/v1/images/generations/{task_id}` 轮询。\n\n顶层 callback_url 可用于图像生成和 JSON 编辑。携带该字段时，成功提交返回 CR id、pending 状态和 poll_url，CR 仅投递 completed 或 failed 终态，正文与终态 GET 响应逐字节一致。同步模型仍需等待本次生成结束，结果保存后由后台投递，不会再次生成。不传 callback_url 时保持原有同步或异步响应。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" }, "example": { "model": "IMAGE_EDIT_MODEL_NAME", "prompt": "Change the background to a plain light gray.", "image": "https://your-assets.example/reference.png" } } } }, "responses": { "200": { "description": "编辑后的图像结果，或已接受的异步图像任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "description": "请求无效。回调地址无效时返回 invalid_callback_url；provider_options 内的 callback_url 返回 reserved_parameter。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "502": { "$ref": "#/components/responses/ModelServiceError" }, "503": { "description": "回调配置或持久化不可用时返回 callback_unavailable。模型服务已接受但结果保存失败时也可能返回此错误，不应盲目重复提交。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "createUnifiedV1ImagesEdits", "callbacks": { "imageTerminal": { "$ref": "#/components/callbacks/CrImageTerminal" } } } }, "/unified/v1/images/generations/{task_id}": { "get": { "tags": [ "Image" ], "summary": "轮询图像生成任务", "description": "获取先前提交的图像生成任务的当前状态及（达到终态时的）结果。只有提交该任务的密钥才能轮询自己的任务。启用回调的任务返回已保存的终态正文，与回调逐字节一致。", "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "当前任务状态；完成时 `data` 已填充。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "任务未找到，或不属于请求方密钥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "502": { "$ref": "#/components/responses/ModelServiceError" }, "503": { "$ref": "#/components/responses/Overloaded" } }, "operationId": "getUnifiedV1ImagesGenerationsByTaskId" } }, "/unified/v1/videos/generations": { "post": { "tags": [ "Video" ], "summary": "提交视频生成", "description": "旧接口继续兼容，尚未废弃。新接入推荐 POST /unified/v1/videos/tasks；详见[异步媒体任务](/docs/zh/media-tasks)。\n\n提交一个视频生成任务。顶层 `callback_url` 对所有视频模型生效；任务达到 `completed` 或 `failed` 后，CR 向该地址发送终态响应。回调正文与相同任务的终态查询响应逐字节一致。使用响应中的 `id` 实现幂等处理，并保存 `poll_url` 以便对账。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerationRequest" }, "example": { "model": "MODEL_NAME", "content": [ { "type": "text", "text": "海边日落" } ], "duration": 8, "callback_url": "https://customer.example.com/webhooks/cr-video" } } } }, "responses": { "200": { "description": "已受理的视频生成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTaskResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "description": "请求无效。`callback_url` 不符合安全规则时返回 `invalid_callback_url`；在 `provider_options` 中提供该字段时返回 `reserved_parameter`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "502": { "$ref": "#/components/responses/ModelServiceError" }, "503": { "description": "没有可用模型路由，或请求了回调但当前环境无法持久化回调登记。后一种情况返回 `callback_unavailable`，且不会提交视频任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "callbacks": { "videoTerminal": { "{$request.body#/callback_url}": { "post": { "summary": "接收视频终态回调", "description": "仅当请求包含 `callback_url` 时发送。正文是状态为 `completed` 或 `failed` 的 CR 视频任务响应。重试使用相同正文。接收方按任务 `id` 去重，持久化结果后返回任意 2xx。", "security": [], "parameters": [ { "name": "user-agent", "in": "header", "required": true, "description": "固定为 `CR-Webhook/1.0`。", "schema": { "type": "string", "const": "CR-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrVideoTerminalCallback" } } } }, "responses": { "2XX": { "description": "接收方已持久化或已处理该任务 `id`。" } } } } } }, "operationId": "createUnifiedV1VideosGenerations" } }, "/unified/v1/videos/generations/{task_id}": { "get": { "tags": [ "Video" ], "summary": "轮询视频生成任务", "description": "获取先前提交的视频生成任务的当前状态及（达到终态时的）结果。只有提交该任务的密钥才能轮询自己的任务。", "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "当前任务状态；完成时 `data` 已填充。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTaskResponse" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "任务未找到，或不属于请求方密钥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "502": { "$ref": "#/components/responses/ModelServiceError" } }, "operationId": "getUnifiedV1VideosGenerationsByTaskId" } }, "/unified/v1/assets": { "post": { "tags": [ "Assets" ], "summary": "导入人像图片", "operationId": "createUnifiedV1Asset", "description": "每次上传指定 model，group_id 可选。保存原文件后立即入库并默认等待最多 30 秒。HTTP 201 表示资源已创建，状态可能为 Active、Failed 或 Processing；仍 Processing 时再查 GET。每团队默认 10 GiB、1,000 份素材；文件 20 MiB、Base64 解码后 5 MiB。元数据在 multipart 文件前发送。相同 Idempotency-Key 重放不重复上传，可改变等待时长。素材不单独收费。 [Guide](/docs/zh/media-assets).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMediaAsset" } }, "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "file" ], "properties": { "group_id": { "type": "string", "format": "uuid", "description": "可选团队业务组 ID；省略时进入团队默认组。" }, "name": { "type": "string", "maxLength": 256 }, "expires_at": { "type": "integer" }, "file": { "type": "string", "format": "binary", "maxLength": 20971520 }, "model": { "type": "string", "minLength": 1, "maxLength": 512, "description": "从 GET /unified/v1/models?capability=portrait_assets 选择模型，用于首次入库，不限制兼容模型复用。" } }, "description": "先发送 model、可选 group_id/name/expires_at，最后发送一个 file。" } } } }, "responses": { "201": { "description": "资源已创建；检查 status，不以 201 判断入库成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsset" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "Location": { "schema": { "type": "string" }, "description": "资源查询路径。" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Processing 时为 2 秒。" } } }, "400": { "description": "invalid_asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "模型访问被拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "模型或素材组不存在，或对当前 API Key 不可见。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "idempotency_conflict or asset_target_not_ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "asset_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "asset_quota_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "wait_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 30, "default": 30 }, "description": "原文件保存后的最长等待秒数。0 立即返回，后台任务不受连接断开影响。" } ] }, "get": { "tags": [ "Assets" ], "summary": "分页查询素材", "operationId": "listUnifiedV1Assets", "description": "查询当前团队未删除、未过期的素材。按 ID 倒序，next_cursor 用作 before。", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "group_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "Processing", "Active", "Failed" ] } } ], "responses": { "200": { "description": "素材列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAssetList" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "400": { "description": "invalid_asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/unified/v1/assets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Assets" ], "summary": "查询素材元数据", "operationId": "getUnifiedV1Asset", "description": "当前团队可读；其他团队返回 404。状态查询立即返回快照。", "responses": { "200": { "description": "素材元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsset" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "asset_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "tags": [ "Assets" ], "summary": "删除素材", "operationId": "deleteUnifiedV1Asset", "description": "创建者可删除；默认组不能整体删除。立即禁止新引用及预览，已受理任务结束后异步清理。", "responses": { "204": { "description": "已删除或已安排清理，无响应体。", "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "asset_write_forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "tags": [ "Assets" ], "summary": "修改资源名称或说明", "operationId": "updateUnifiedV1Asset", "description": "仅创建者可修改；默认组不可修改。不触发重新入库。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } } } } } }, "responses": { "200": { "description": "素材元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsset" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "400": { "description": "invalid_asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "asset_write_forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "asset_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/meter": { "post": { "tags": [ "Metering" ], "summary": "上报一笔计量事件", "description": "适用于已开通通用计量能力的服务端集成。按 SKU code 上报数量，由 CR 定价并记录消费。响应中的 charged 表示本次费用，balance_after 表示扣费后余额，单位均为 Credits（ℂ），与控制台一致。\n\n**按数量计费**：金额类 SKU 以 `元` 为单位，例如“花费 10 元”填写 `quantity = 10`；单价由 CR 维护，调用方只上报实际数量。\n\n**幂等**：同一 API Key 使用相同 `idempotency_key` 重试不会重复扣费，响应以 `deduped: true` 标记并返回首次记录的 `charged`。同一个 `idempotency_key` 携带不同参数会返回 409。\n\n**预算检查**：正式上报会记录实际发生的费用，即使响应中的 `budget_ok` 为 `false`。需要在动作执行前检查预算时，先使用 `dry_run: true`；该结果是即时估算，不会预留额度。\n\n`occurred_at` 可填写最近 90 天内的时间，允许最多 5 分钟的未来时钟偏差；超出范围返回 400。请求体上限为 64 KB。\n\n金额以精确十进制字符串返回，最多六位小数，不固定补零。正式上报、dry_run 和幂等重试的成功响应均通过 X-CRR-Credit-Unit: credits 标明金额单位。单次费用上限为 50000000000 ℂ。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterReportRequest" }, "example": { "sku": "websearch", "idempotency_key": "evt_01J9ZK3V7Q", "quantity": 3, "meta": { "user_id": "u_123", "feature": "deep-research" } } } } }, "responses": { "200": { "description": "计费结果。`dry_run` 请求同样返回 200，`balance_after` 为 null 且带 `dry_run: true`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterReportResponse" }, "examples": { "recorded": { "value": { "charged": "3", "deduped": false, "budget_ok": true, "balance_after": "47" } }, "dry_run": { "value": { "charged": "0.000005", "deduped": false, "budget_ok": true, "balance_after": null, "dry_run": true } }, "replay": { "value": { "charged": "3", "deduped": true, "budget_ok": true, "balance_after": null } } } } }, "headers": { "X-CRR-Credit-Unit": { "schema": { "type": "string", "const": "credits" }, "description": "响应中金额字段的单位：Credits（ℂ）。" }, "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "X-CR-Usage-ID": { "$ref": "#/components/headers/CrUsageId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`sku` 不存在于计量目录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "405": { "description": "非 POST 方法。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "`idempotency_key` 已被一笔参数不同的事件使用；本次未做任何记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "503": { "$ref": "#/components/responses/Overloaded" } }, "operationId": "createV1Meter", "x-crr-credit-unit": "credits" } }, "/unified/v1/asset-groups": { "post": { "tags": [ "Assets" ], "summary": "创建人像素材组", "operationId": "createUnifiedV1AssetGroup", "description": "创建团队业务组；无需模型。未传 group_id 的上传使用系统默认组。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetGroup" } } } }, "responses": { "201": { "description": "Group created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetGroup" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "400": { "description": "invalid_asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "model_access_denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "idempotency_conflict or asset_target_not_ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "asset_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "asset_quota_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] }, "get": { "tags": [ "Assets" ], "summary": "分页查询人像素材组", "operationId": "listUnifiedV1AssetGroups", "description": "查询当前团队的业务组及默认组。", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "query", "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "素材列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetGroupList" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "400": { "description": "invalid_asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/unified/v1/asset-groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Assets" ], "summary": "查询人像素材组", "operationId": "getUnifiedV1AssetGroup", "description": "当前团队可读；其他团队返回 404。状态查询立即返回快照。", "responses": { "200": { "description": "素材元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetGroup" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "asset_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "tags": [ "Assets" ], "summary": "删除人像素材组", "operationId": "deleteUnifiedV1AssetGroup", "description": "创建者可删除；默认组不能整体删除。立即禁止新引用及预览，已受理任务结束后异步清理。", "responses": { "204": { "description": "已删除或已安排清理，无响应体。", "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "asset_write_forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "tags": [ "Assets" ], "summary": "修改资源名称或说明", "operationId": "updateUnifiedV1AssetGroup", "description": "仅创建者可修改；默认组不可修改。不触发重新入库。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": [ "string", "null" ], "maxLength": 2048 } } } } } }, "responses": { "200": { "description": "素材元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetGroup" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "400": { "description": "invalid_asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "asset_write_forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "asset_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/unified/v1/assets/{id}/prepare": { "post": { "tags": [ "Assets" ], "summary": "为一份素材准备另一个素材库", "operationId": "prepareUnifiedV1Asset", "description": "创建者指定模型。兼容库直接复用，新库从已存原文件准备。默认等待 30 秒；查看 targets 中本次模型的状态，不向同组其他素材分发。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model" ], "properties": { "model": { "type": "string" } } } } } }, "responses": { "202": { "description": "Preparation queued or already prepared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsset" } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" }, "Location": { "schema": { "type": "string" }, "description": "资源查询路径。" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Processing 时为 2 秒。" } } }, "400": { "description": "invalid_asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "asset_write_forbidden or model_access_denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "idempotency_conflict or asset_target_not_ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "asset_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "asset_quota_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "wait_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 30, "default": 30 }, "description": "原文件保存后的最长等待秒数。0 立即返回，后台任务不受连接断开影响。" } ] } }, "/unified/v1/assets/{id}/preview": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Assets" ], "summary": "获取临时预览地址", "operationId": "previewUnifiedV1Asset", "description": "同团队可申请，无需正文。签名不暴露原文件地址；到期、删除、签发 Key 撤销后失效。预览可用不表示入库 Active。", "responses": { "200": { "description": "有效 120 秒的预览地址。", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "integer" } } } } }, "headers": { "X-CR-Request-ID": { "$ref": "#/components/headers/CrRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "asset_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "asset_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "asset_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "CR API Key，通过 `Authorization: Bearer ` 发送。" } }, "parameters": { "TaskId": { "name": "task_id", "in": "path", "required": true, "description": "提交时返回的异步生成任务标识符。", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "请求无效（例如缺少 `model`、请求体格式错误、UTF-8 非法）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "Unauthorized": { "description": "API Key 缺失、格式错误、无效或已过期。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "Forbidden": { "description": "该密钥无权使用所请求的模型。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "NotFound": { "description": "所请求的模型不存在或已禁用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "PayloadTooLarge": { "description": "请求体超过允许的最大大小。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "Overloaded": { "description": "模型已识别，但当前没有可用路由。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "ModelServiceError": { "description": "模型服务暂不可用或返回了错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "schemas": { "MediaTaskResponse": { "type": "object", "description": "图片、编辑和视频共用的 CR 任务对象。始终包含 id、status、model、created_at。", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "例如 `pending`、`processing`、`completed`、`failed`。", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": "integer" }, "completed_at": { "type": "integer", "description": "任务达到终态的 Unix 秒时间戳。" }, "model": { "type": "string" }, "poll_url": { "type": "string", "description": "用于轮询完成情况的 URL。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaTaskResult" } }, "usage": { "$ref": "#/components/schemas/UsageInfo" }, "error": { "$ref": "#/components/schemas/ApiError" }, "request_id": { "type": "string", "format": "uuid", "description": "失败终态中最初提交任务的 CR 请求标识。查询、幂等重试和回调使用同一份正文，此值不变；本次查询请求的标识在 x-cr-request-id 响应头。旧任务可能省略。" }, "tools": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/MediaToolExecution" }, "description": "任务级工具执行统计，不在各视频中重复。仅提供信息，不参与费用计算；未报告时省略。请求启用工具不代表实际调用。" }, "extensions": { "$ref": "#/components/schemas/MediaResultExtensions" } }, "required": [ "id", "status", "created_at", "model" ] }, "ApiError": { "type": "object", "description": "遵循 OpenAI 错误格式的结构化错误。", "properties": { "type": { "type": "string", "description": "错误类别：`authentication_error`、`permission_error`、`not_found_error`、`invalid_request_error`、`overloaded_error`、`rate_limit_error`、`timeout_error`、`upstream_error`、`internal_error`。CR 不会返回模型供应商自己的错误类别。素材接口错误使用 asset_error。" }, "code": { "type": "string", "description": "CR 的机器可读错误码。HTTP 错误响应和异步任务终态中的模型失败归类使用封闭集合：`content_policy_violation`、`invalid_parameter`、`input_too_large`、`unsupported_capability`、`upstream_rate_limited`、`quota_exceeded`、`model_unavailable`、`request_timeout`，未归类时为 `upstream_request_failed`。异步任务终态沿用相同原因码，未归类时为 `task_failed`，取消时为 `task_cancelled`。常见请求与鉴权类：`invalid_api_key`、`model_access_denied`、`model_not_found`、`task_not_found`、`invalid_callback_url`、`reserved_parameter`、`conflicting_reasoning_parameters`、`invalid_reasoning_parameters`、`unsupported_reasoning_parameters`、`callback_unavailable`、`no_routes_available`、`provider_unavailable`。HTTP 错误响应和异步任务终态错误使用 CR 定义的错误码，不使用模型供应商自己的错误码。完整含义、处理建议和流式错误的独立行为见[错误码](/docs/zh/troubleshooting#错误响应格式)。素材错误还包括 invalid_asset、asset_not_found、asset_expired、asset_too_large、asset_quota_exceeded、asset_unavailable、asset_preparation_failed、asset_submission_unknown。" }, "message": { "type": "string", "description": "CR 编写的可读错误说明，已识别的诊断包含具体原因和纠错建议，不包含供应商身份、真实模型、内部地址或凭据。已识别的上下文窗口超限保留 prompt is too long 前缀以兼容客户端。其他文案可调整，程序应按 code 分支。" }, "param": { "type": "string", "description": "可安全确定的请求字段，例如 content[1].image_url.url、provider_options.image_urls[0] 或 output_config.format。本地校验及已识别的模型错误可以返回此字段；无法确定时省略。" } }, "required": [ "type", "code", "message" ] }, "ApiErrorEnvelope": { "type": "object", "description": "即时 HTTP 错误的传输信封。request_id 与响应头 x-cr-request-id 相同，方便只解析 JSON 的客户端。异步失败终态使用 MediaTaskResponse，其中的 request_id 标识最初提交任务的请求。", "properties": { "error": { "$ref": "#/components/schemas/ApiError" }, "request_id": { "type": "string", "format": "uuid", "description": "本次 HTTP 尝试的 CR 请求 ID，与响应头 x-cr-request-id 相同。" } }, "required": [ "error", "request_id" ] }, "UsageInfo": { "type": "object", "description": "自由格式的用量/计费计数器；键随操作和模型而异（基于 token 的操作会规范化为 `input:*` / `output:*` 键）。", "additionalProperties": true }, "ReasoningEffort": { "type": "string", "description": "标准推理强度。`none` 请求关闭推理；档位不是固定 token 预算。所选模型可能只支持其中一部分。", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "ChatCompletionRequest": { "type": "object", "description": "兼容 OpenAI 的对话补全请求。未列出的扩展字段会被保留，是否生效取决于所选模型。", "properties": { "model": { "type": "string", "description": "从模型目录选择的模型名称。" }, "messages": { "type": "array", "description": "按时间顺序排列的对话消息。", "items": { "type": "object", "additionalProperties": true } }, "stream": { "type": "boolean", "description": "为 true 时返回 `text/event-stream`。" }, "reasoning_effort": { "$ref": "#/components/schemas/ReasoningEffort", "description": "Chat Completions 的标准推理强度。省略时保留模型默认行为。" }, "tools": { "type": "array", "description": "所选模型支持的工具或函数定义。", "items": { "type": "object", "additionalProperties": true } }, "tool_choice": { "description": "工具选择指令。" }, "response_format": { "description": "所选模型支持的结构化输出格式。" }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "max_tokens": { "type": "integer", "minimum": 0 }, "max_completion_tokens": { "type": "integer", "minimum": 0 }, "n": { "type": "integer", "minimum": 1 }, "seed": { "type": "integer" }, "stop": { "description": "停止序列：字符串或数组。" }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "logprobs": { "type": "boolean" }, "top_logprobs": { "type": "integer", "minimum": 0 }, "parallel_tool_calls": { "type": "boolean" }, "user": { "type": "string" }, "metadata": { "type": "object", "description": "随请求传递的任意元数据。", "additionalProperties": true } }, "required": [ "model", "messages" ], "additionalProperties": true }, "ChatCompletionResponse": { "type": "object", "description": "非流式对话补全响应，可能包含所选模型返回的扩展字段。", "properties": { "id": { "type": "string" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/UsageInfo" } }, "required": [ "id", "object", "created", "model", "choices" ], "additionalProperties": true }, "ResponseRequest": { "type": "object", "description": "OpenAI Responses API 请求。", "properties": { "model": { "type": "string" }, "input": { "description": "字符串或输入项数组。" }, "instructions": { "type": "string" }, "previous_response_id": { "type": "string", "description": "从先前的响应续接（以调用方密钥为作用域）。" }, "stream": { "type": "boolean" }, "background": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_choice": { "description": "工具选择指令。" }, "reasoning": { "type": "object", "description": "Responses 的统一推理配置。使用 `effort` 控制推理强度。", "properties": { "effort": { "$ref": "#/components/schemas/ReasoningEffort" } }, "additionalProperties": true }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "max_output_tokens": { "type": "integer", "minimum": 0 }, "store": { "type": "boolean" }, "truncation": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "model", "input" ], "additionalProperties": true }, "ResponseObject": { "type": "object", "description": "Responses API 结果，可能包含所选模型返回的扩展字段。", "properties": { "id": { "type": "string" }, "object": { "type": "string", "example": "response" }, "created_at": { "type": "integer" }, "expire_at": { "type": "integer" }, "status": { "type": "string", "description": "例如 `completed`、`pending`、`processing`、`failed`。" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/UsageInfo" } }, "required": [ "id", "object", "created_at", "status", "model" ], "additionalProperties": true }, "EmbeddingRequest": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "description": "文本、文本数组或多模态数组。" }, "dimensions": { "type": "integer", "minimum": 1 }, "normalized": { "type": "boolean", "description": "供应商特定的 L2 归一化选项（例如 Jina）。" }, "embedding_type": { "description": "供应商特定的输出编码格式，例如 float、base64、binary 或 ubinary。" }, "truncate": { "type": "boolean", "description": "供应商特定的超长输入截断选项。" }, "task": { "type": "string", "description": "供应商特定的 Embedding 任务，例如 retrieval.query。" }, "encoding_format": { "type": "string" }, "input_type": { "type": "string" }, "user": { "type": "string" } }, "required": [ "model", "input" ], "additionalProperties": true }, "EmbeddingResponse": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/UsageInfo" } }, "required": [ "object", "model", "data" ] }, "RerankRequest": { "type": "object", "properties": { "model": { "type": "string" }, "query": { "description": "文本或多模态查询对象。" }, "documents": { "type": "array", "description": "待排序的文档。", "items": {} }, "top_n": { "type": "integer", "minimum": 1 }, "return_documents": { "type": "boolean" } }, "required": [ "model", "query", "documents" ], "additionalProperties": true }, "RerankResponse": { "type": "object", "properties": { "model": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/UsageInfo" } }, "required": [ "model", "results" ] }, "ImageGenerationRequest": { "type": "object", "description": "通用图片请求结构。可选字段并非每个模型都支持，尺寸格式、质量、数量和编辑输入需按模型确认。参见[图片与视频参数](/docs/zh/media-tasks#图片参数)中的模型差异和已验证组合。", "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "image": { "description": "参考图像：URL、base64 字符串或数组。" }, "mask": { "description": "支持蒙版编辑的模型可用，必须同时提供 image。接受 URL/base64 字符串或仅包含 image_url 的对象，不支持 file_id。Image 1.5 使用与第一张原图宽高相同的 PNG，Alpha=0 表示编辑区域。mask 放在顶层，不放入 provider_options。", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": [ "image_url" ], "additionalProperties": false, "properties": { "image_url": { "type": "string", "minLength": 1 } } } ] }, "n": { "type": "integer", "minimum": 1 }, "size": { "type": "string", "example": "1024x1024", "description": "模型支持的尺寸字符串。1024x1024、1024*1024、1K 和宽高比不能跨模型互换；示例不是所有模型的默认值。" }, "quality": { "type": "string" }, "aspect_ratio": { "type": "string" }, "negative_prompt": { "type": "string" }, "seed": { "type": "integer" }, "output_format": { "type": "string" }, "response_format": { "type": "string" }, "user": { "type": "string" }, "provider_options": { "type": "object", "description": "模型特定的扩展字段，只使用所选模型已接入的参数。已有通用字段放在顶层，避免重复或冲突。callback_url 在任意嵌套深度都是 CR 保留参数。", "additionalProperties": true }, "callback_url": { "type": "string", "format": "uri", "description": "可选的 CR 终态回调地址，必须为绝对 HTTPS URL，UTF-8 编码后不超过 2048 字节。允许 path 和 query，禁止 userinfo、fragment 和内网目的地址。CR 短期明文保存地址，不发送给模型服务。", "example": "https://customer.example.com/webhooks/cr-image" } }, "required": [ "model", "prompt" ], "additionalProperties": true, "not": { "anyOf": [ { "required": [ "expansion" ] }, { "required": [ "upscale" ] }, { "required": [ "background_removal" ] } ] } }, "ImageGenerationResponse": { "type": "object", "description": "图像接口响应。同步响应可直接包含 `data` 且没有 `id` 或 `status`；异步任务包含 `id` 和 `status`。\n\n顶层 callback_url 可用于图像生成和 JSON 编辑。携带该字段时，成功提交返回 CR id、pending 状态和 poll_url，CR 仅投递 completed 或 failed 终态，正文与终态 GET 响应逐字节一致。同步模型仍需等待本次生成结束，结果保存后由后台投递，不会再次生成。不传 callback_url 时保持原有同步或异步响应。", "properties": { "id": { "type": "string" }, "status": { "type": "string", "description": "例如 `completed`、`pending`、`processing`、`failed`。" }, "created_at": { "type": "integer" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/UsageInfo" }, "error": { "$ref": "#/components/schemas/ApiError" }, "created": { "type": "integer", "description": "同步图像响应的创建时间（Unix 秒）。" }, "poll_url": { "type": "string", "description": "携带 callback_url 时返回的 CR 任务查询路径。" }, "completed_at": { "type": "integer", "description": "终态时间，Unix 秒。" } }, "anyOf": [ { "required": [ "data" ] }, { "required": [ "id", "status" ] } ] }, "VideoGenerationRequest": { "type": "object", "description": "通用视频请求结构。可选字段并非每个模型都支持，时长、清晰度、比例和媒体输入需按模型确认。参见[图片与视频参数](/docs/zh/media-tasks#视频参数)中的模型差异和已验证组合。", "properties": { "model": { "type": "string" }, "content": { "type": "array", "description": "带类型的多模态输入项。", "items": { "$ref": "#/components/schemas/VideoContentItem" } }, "size": { "type": "string" }, "resolution": { "type": "string" }, "aspect_ratio": { "type": "string", "description": "模型相关：部分文生视频必填，部分图生视频禁止填写并跟随输入图。不能统一添加或省略。" }, "duration": { "type": "integer", "minimum": 0, "description": "整数秒数，实际可用范围和默认值由模型决定。不接受字符串或 -1；minimum 只是通用类型边界。" }, "fps": { "type": "integer", "minimum": 0 }, "seed": { "type": "integer" }, "negative_prompt": { "type": "string" }, "callback_url": { "type": "string", "format": "uri", "description": "可选的终态回调地址。必须是绝对 HTTPS URL，UTF-8 编码后不超过 2048 字节；允许 path 和 query，不允许 userinfo、fragment、非公网地址或 CR API 自身地址。只在请求顶层提供该字段。", "example": "https://customer.example.com/webhooks/cr-video" }, "provider_options": { "type": "object", "description": "模型特定的扩展字段，只使用所选模型已接入的参数，例如支持时可使用 watermark 或 generate_audio。不要另包一层 parameters，也不要与顶层字段重复。callback_url 在任意嵌套深度都是保留参数。", "additionalProperties": true } }, "required": [ "model", "content" ], "additionalProperties": true }, "VideoMediaUrl": { "type": "object", "description": "媒体引用：公开 URL、`data:` Base64 URI，或已入库图片的 CR 素材 URI。", "properties": { "url": { "type": "string", "description": "公开图片 URL、支持的 Base64 Data URI，或已入库人像图片的 asset://。" } }, "required": [ "url" ] }, "VideoContentRole": { "type": "string", "enum": [ "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio" ], "description": "输入媒体项的作用；只有所选模型支持的作用类型会生效。" }, "VideoContentItem": { "type": "object", "description": "视频内容。image_url.url 支持 asset://，引用同一 API Key 创建且状态为 Active 的人像图片。type=asset 配合 asset_id 是等价写法。直接 HTTPS 或 Data URI 输入不会创建素材，也不会自动入库。", "oneOf": [ { "type": "object", "properties": { "type": { "const": "text" }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "const": "image_url" }, "image_url": { "$ref": "#/components/schemas/VideoMediaUrl" }, "role": { "$ref": "#/components/schemas/VideoContentRole" } }, "required": [ "type", "image_url" ] }, { "type": "object", "properties": { "type": { "const": "video_url" }, "video_url": { "$ref": "#/components/schemas/VideoMediaUrl" }, "role": { "$ref": "#/components/schemas/VideoContentRole" } }, "required": [ "type", "video_url" ] }, { "type": "object", "properties": { "type": { "const": "input_audio" }, "input_audio": { "$ref": "#/components/schemas/VideoMediaUrl" }, "role": { "$ref": "#/components/schemas/VideoContentRole" } }, "required": [ "type", "input_audio" ] }, { "type": "object", "required": [ "type", "asset_id" ], "properties": { "type": { "const": "asset" }, "asset_id": { "type": "string", "format": "uuid" }, "role": { "type": [ "string", "null" ], "enum": [ "reference_image", "first_frame", "last_frame", null ], "description": "省略时使用 reference_image；必须符合模型能力。" } }, "description": "由当前 API Key 创建、已为请求模型完成入库且状态为 Active 的人像图片。" } ] }, "VideoTaskResponse": { "type": "object", "description": "异步视频生成任务状态。", "properties": { "id": { "type": "string" }, "status": { "type": "string", "description": "例如 `pending`、`processing`、`completed`、`failed`。" }, "created_at": { "type": "integer" }, "completed_at": { "type": "integer", "description": "任务达到终态的 Unix 秒时间戳。" }, "model": { "type": "string" }, "poll_url": { "type": "string", "description": "用于轮询完成情况的 URL。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoResult" } }, "usage": { "$ref": "#/components/schemas/UsageInfo" }, "error": { "$ref": "#/components/schemas/ApiError" }, "tools": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/MediaToolExecution" }, "description": "任务级工具执行统计，不在各视频中重复。仅提供信息，不参与费用计算；未报告时省略。请求启用工具不代表实际调用。" }, "extensions": { "$ref": "#/components/schemas/MediaResultExtensions" } }, "required": [ "id", "status", "created_at", "model" ] }, "CrVideoTerminalCallback": { "allOf": [ { "$ref": "#/components/schemas/VideoTaskResponse" }, { "type": "object", "description": "CR 发送到客户 callback_url 的终态正文。该正文与终态查询响应逐字节一致。", "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ] } } } ] }, "MeterReportRequest": { "type": "object", "properties": { "sku": { "type": "string", "example": "websearch", "description": "计量目录中注册的稳定 SKU 代码。" }, "idempotency_key": { "type": "string", "example": "evt_01J9ZK3V7Q", "description": "调用方生成的事件唯一 id，是唯一的幂等键：相同值重试永不重复扣费。仅 `dry_run` 请求可省略。" }, "quantity": { "type": [ "number", "string" ], "example": 3, "description": "消耗数量，按 SKU 定义的单位填写。接受 JSON 数字或十进制字符串，范围为 0–1e12；需要保留小数精度时建议使用字符串。金额类 SKU 的单位为元，例如花费 10 元时填写 10。" }, "occurred_at": { "type": "string", "format": "date-time", "description": "事件发生时间，原样作为记录的 `created_at`。缺省为当前时间；必须落在最近 90 天内（未来至多 5 分钟）。" }, "dry_run": { "type": "boolean", "default": false, "description": "预检模式：校验、询价并跑预算门槛，但不落任何记录 —— 用于在执行动作前确认\"这个用户还能不能消费\"。" }, "meta": { "type": "object", "description": "调用方自定义上下文，原样存入记录的 metadata 供追溯。" } }, "required": [ "sku", "idempotency_key", "quantity" ] }, "MeterReportResponse": { "type": "object", "properties": { "charged": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]{1,6})?$", "x-crr-unit": "credits", "description": "本次费用，单位为 Credits（ℂ），以最多六位小数的精确十进制字符串返回。dry_run 返回预估费用；幂等重试返回首次记录的费用。" }, "deduped": { "type": "boolean", "description": "true 表示该 `idempotency_key` 此前已入账，本次未重复扣费。" }, "budget_ok": { "type": "boolean", "description": "预算门槛结论：false 表示该密钥/团队/组织已被超支系统标记。真实上报即使为 false 也已入账 —— 请用 `dry_run` 在动作前拦截。" }, "balance_after": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+(?:\\.[0-9]{1,6})?$", "x-crr-unit": "credits", "description": "扣费后的缓存余额，单位为界面 Credits（ℂ），最多六位小数，可为负数。预估、幂等重试、零扣费或缓存不可用时为 null，不代表零余额。" }, "dry_run": { "type": "boolean", "description": "仅 dry-run 响应中出现且为 true。" } }, "required": [ "charged", "deduped", "budget_ok", "balance_after" ] }, "CrImageTerminalCallback": { "allOf": [ { "$ref": "#/components/schemas/ImageGenerationResponse" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ] } }, "required": [ "id", "status", "created_at", "completed_at", "model" ] } ] }, "ModelDescription": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "created", "owned_by" ], "properties": { "id": { "type": "string", "description": "请求中使用的模型名称。" }, "object": { "type": "string", "const": "model" }, "created": { "type": "integer", "format": "int64", "description": "模型在 CR 中创建的 Unix 时间戳，单位为秒。" }, "owned_by": { "type": "string", "const": "cr" }, "context_window": { "type": "integer", "minimum": 1, "description": "上下文总窗口，单位为 tokens。输入和输出共享此预算；具体模型也可能有单独的输入限制。" }, "context_length": { "type": "integer", "minimum": 1, "description": "`context_window` 的兼容别名，数值与其相同。" }, "max_output_tokens": { "type": "integer", "minimum": 1, "description": "单次生成的最大输出预算，单位为 tokens；实际可生成长度也受剩余上下文预算约束。" }, "capabilities": { "type": "object", "additionalProperties": false, "properties": { "image_outpaint": { "type": "object", "additionalProperties": false, "required": [ "expansion_units", "ratio_step", "max_ratio_per_side", "max_area_factor", "max_outputs", "input_types", "prompt" ], "properties": { "expansion_units": { "type": "array", "items": { "const": "ratio" } }, "ratio_step": { "const": 0.0001 }, "max_ratio_per_side": { "const": 2 }, "max_area_factor": { "const": 3 }, "max_outputs": { "const": 1 }, "input_types": { "type": "array", "items": { "const": "https_url" } }, "prompt": { "type": "object", "additionalProperties": false, "required": [ "required", "max_length" ], "properties": { "required": { "const": true }, "max_length": { "const": 2500 } } } } } } } } }, "ModelList": { "type": "object", "additionalProperties": false, "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelDescription" } } } }, "MediaAsset": { "type": "object", "required": [ "id", "object", "status", "media_type", "mime_type", "bytes", "created_at", "expires_at", "error", "group_id", "name", "targets", "model", "stage", "permissions" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "CR 素材 UUID；生成时作为 asset_id。" }, "object": { "type": "string", "const": "asset" }, "status": { "type": "string", "enum": [ "Processing", "Active", "Failed" ] }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", null ] }, "mime_type": { "type": [ "string", "null" ] }, "bytes": { "type": "integer", "minimum": 0 }, "created_at": { "type": "integer", "description": "Unix 秒时间戳。" }, "expires_at": { "type": [ "integer", "null" ], "description": "null 表示长期保存；与生成结果有效期独立。" }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" } }, "required": [ "code" ] }, "group_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/AssetTarget" } }, "model": { "type": "string", "description": "上传时选择的模型。" }, "stage": { "type": "string", "description": "当前处理阶段。现有值为 uploading、queued、registering、ready、failed；允许以后增加阶段。生成就绪条件为 status=Active，客户端不能依赖固定阶段或顺序。", "examples": [ "queued", "registering", "ready" ] }, "permissions": { "type": "object", "required": [ "can_update", "can_delete", "can_prepare" ], "properties": { "can_update": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "can_prepare": { "type": "boolean" } } } }, "description": "团队共享人像素材；Active 对应首次入库目标。targets 为明确准备记录，不是生成模型白名单。", "example": { "id": "019a1234-5678-7000-8000-000000000001", "object": "asset", "status": "Processing", "media_type": "image", "mime_type": "image/jpeg", "bytes": 485747, "created_at": 1789862400, "expires_at": null, "error": null, "group_id": "019a1234-5678-7000-8000-000000000002", "name": "Portrait", "targets": [ { "model": "YOUR_MODEL_NAME", "status": "Processing", "error": null, "stage": "queued" } ], "model": "YOUR_MODEL_NAME", "stage": "queued", "permissions": { "can_update": true, "can_delete": true, "can_prepare": true } } }, "MediaAssetList": { "type": "object", "required": [ "object", "data", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaAsset" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } }, "CreateMediaAsset": { "type": "object", "additionalProperties": false, "properties": { "group_id": { "type": "string", "format": "uuid", "description": "可选团队业务组 ID；省略时进入团队默认组。" }, "name": { "type": [ "string", "null" ], "maxLength": 256 }, "url": { "type": "string", "format": "uri", "description": "公开 HTTPS 地址，不允许重定向。CR 下载并保存原文件。" }, "base64": { "type": "string", "description": "原始 Base64 或图片 Data URI；解码后默认上限 5 MiB。" }, "expires_at": { "type": [ "integer", "null" ], "description": "null 表示长期保存；与生成结果有效期独立。" }, "model": { "type": "string", "minLength": 1, "maxLength": 512, "description": "从 GET /unified/v1/models?capability=portrait_assets 选择模型，用于首次入库，不限制兼容模型复用。" } }, "oneOf": [ { "required": [ "url" ], "not": { "required": [ "base64" ] } }, { "required": [ "base64" ], "not": { "required": [ "url" ] } } ], "example": { "model": "YOUR_MODEL_NAME", "url": "https://example.com/portrait.jpg" }, "required": [ "model" ] }, "AssetTarget": { "type": "object", "required": [ "model", "status" ], "properties": { "model": { "type": "string" }, "status": { "type": "string", "enum": [ "Processing", "Active", "Failed" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" } }, "required": [ "code" ] }, "active": { "type": "integer" }, "processing": { "type": "integer" }, "failed": { "type": "integer" }, "stage": { "type": "string", "description": "素材目标的处理阶段；组的汇总目标不返回此字段。", "examples": [ "queued", "registering", "ready" ] } } }, "AssetGroup": { "type": "object", "required": [ "id", "object", "name", "description", "is_default", "created_at", "asset_count", "bytes", "storage_bytes", "pending_cleanup_count", "permissions" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "asset_group" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "asset_count": { "type": "integer" }, "bytes": { "type": "integer" }, "storage_bytes": { "type": "integer" }, "pending_cleanup_count": { "type": "integer" }, "permissions": { "type": "object", "required": [ "can_update", "can_delete" ], "properties": { "can_update": { "type": "boolean" }, "can_delete": { "type": "boolean" } } } } }, "CreateAssetGroup": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": [ "string", "null" ], "maxLength": 2048 } } }, "AssetGroupList": { "type": "object", "required": [ "object", "data", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetGroup" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } }, "VideoResult": { "type": "object", "additionalProperties": true, "required": [ "url" ], "description": "每项对应一个成片，尾帧属于同一项。可选元数据描述生成结果，不代表请求设置。字段含义统一，可用性因模型而异；客户端须兼容新增可选字段。", "properties": { "type": { "type": "string", "const": "video", "description": "标准视频结果为 video；历史结果可能省略。" }, "url": { "type": "string", "format": "uri", "description": "视频下载链接。" }, "last_frame_url": { "type": "string", "format": "uri", "description": "该视频的尾帧图片下载链接。支持此功能的模型可设置 provider_options.return_last_frame。未返回尾帧时省略；查询和回调包含相同的有时效链接。" }, "duration": { "type": "number", "exclusiveMinimum": 0, "description": "报告的成片时长，单位秒，保留小数；不是任务处理耗时。" }, "width": { "type": "integer", "minimum": 1, "description": "报告的视频像素宽度。" }, "height": { "type": "integer", "minimum": 1, "description": "报告的视频像素高度。" }, "size": { "type": "string", "pattern": "^[1-9][0-9]*x[1-9][0-9]*$", "description": "像素尺寸，如 1280x720；宽高完整时由宽高生成。" }, "resolution": { "type": "string", "description": "报告的分辨率档位，如 720p；不根据请求或像素尺寸推断。" }, "aspect_ratio": { "type": "string", "pattern": "^[1-9][0-9]*:[1-9][0-9]*$", "description": "报告的具体比例；缺失时可由宽高约分得到，不返回 adaptive。" }, "fps": { "type": "number", "exclusiveMinimum": 0, "description": "报告的每秒帧数，支持小数。" }, "frame_count": { "type": "integer", "minimum": 1, "description": "报告的总帧数，不根据时长和帧率估算。" }, "has_audio": { "type": "boolean", "description": "报告的成片是否含音频；保留 false，未知时省略。" }, "format": { "type": "string", "description": "报告的容器格式，如 mp4；不根据链接推断。" }, "seed": { "type": "integer", "minimum": 0, "description": "报告的实际种子；未知和随机占位值省略。" }, "extensions": { "$ref": "#/components/schemas/MediaResultExtensions", "description": "已定义的产物特有字段；无可用字段时省略。" } } }, "MediaTaskResult": { "anyOf": [ { "$ref": "#/components/schemas/VideoResult" }, { "type": "object", "additionalProperties": true, "not": { "required": [ "type" ], "properties": { "type": { "const": "video" } } } } ], "description": "视频结果或模型特定的图片及历史媒体结果。图片保留 URL、Base64、尺寸等支持字段。" }, "MediaToolExecution": { "type": "object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search" ], "description": "CR 定义的工具类型。" }, "calls": { "type": "integer", "minimum": 0, "description": "报告的调用次数；明确为 0 时保留，未知时省略。" } } }, "MediaResultExtensions": { "type": "object", "additionalProperties": false, "description": "仅承载已定义类型的扩展字段。当前未定义扩展字段，响应省略此对象。" }, "ImageExpansion": { "type": "object", "additionalProperties": false, "required": [ "unit", "top", "bottom", "left", "right" ], "description": "四向扩图比例，以原图宽高为基准。必须满足 1 < (1+top+bottom)×(1+left+right) ≤ 3。按精确十进制校验；不能用更多小数位近似边界。", "properties": { "unit": { "type": "string", "const": "ratio" }, "top": { "type": "number", "minimum": 0, "maximum": 2, "multipleOf": 0.0001 }, "bottom": { "type": "number", "minimum": 0, "maximum": 2, "multipleOf": 0.0001 }, "left": { "type": "number", "minimum": 0, "maximum": 2, "multipleOf": 0.0001 }, "right": { "type": "number", "minimum": 0, "maximum": 2, "multipleOf": 0.0001 } } }, "ImageOutpaintRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "image", "prompt", "expansion" ], "properties": { "model": { "type": "string", "description": "从 GET /unified/v1/models?capability=image_outpaint 返回的 data[].id 选择。model 决定操作，expansion 仅提供参数。" }, "prompt": { "type": "string", "maxLength": 2500, "description": "必填，可为空；最多 2500 个 Unicode 字符。" }, "image": { "type": "string", "format": "uri", "pattern": "^https://", "description": "一张公开可访问的 HTTPS 图片 URL，不接受数组、Base64、用户名密码、片段或私有地址。" }, "expansion": { "$ref": "#/components/schemas/ImageExpansion" }, "n": { "type": "integer", "const": 1, "default": 1 }, "response_format": { "type": "string", "const": "url", "default": "url" }, "provider_options": { "type": "object", "maxProperties": 0 }, "user": { "type": "string" }, "callback_url": { "type": "string", "format": "uri", "description": "可选的 CR 终态回调地址，必须为绝对 HTTPS URL，UTF-8 编码后不超过 2048 字节。允许 path 和 query，禁止 userinfo、fragment 和内网目的地址。CR 短期明文保存地址，不发送给模型服务。", "example": "https://customer.example.com/webhooks/cr-image" } }, "description": "仅用于 POST /unified/v1/images/edit-tasks 的扩图模型。单次返回一张图片；不支持蒙版、尺寸、质量、seed 或原生参数覆盖。" } }, "callbacks": { "CrImageTerminal": { "{$request.body#/callback_url}": { "post": { "summary": "接收图像终态回调", "description": "正文是保存后的 CR 图像终态响应。data 保留模型返回的 url 或 b64_json。失败或取消时 status=failed，不包含 data 或 usage。按 CR 任务 id 去重，持久化后返回任意 2xx。首次投递失败后最多重试 3 次，间隔 1、2、4 秒。不需要签名或 JWKS。", "security": [], "parameters": [ { "name": "user-agent", "in": "header", "required": true, "description": "固定为 `CR-Webhook/1.0`。", "schema": { "type": "string", "const": "CR-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrImageTerminalCallback" } } } }, "responses": { "2XX": { "description": "接收方已持久化或已处理该任务 `id`。" } } } } } }, "headers": { "CrRequestId": { "description": "本次 HTTP 请求的排障 UUID。每次轮询和重试都有独立值；查账使用 X-CR-Usage-ID。", "schema": { "type": "string", "format": "uuid" } }, "CrUsageId": { "description": "稳定的账单 UUID。用它调用 GET /api/v1/management/usage/{usage_id}。异步轮询和幂等重试继续返回原始用量 ID；存在此头不代表已完成计费或账单立即可查。未关联账单的响应（例如 /v1/meter 的 dry_run）不返回此头。", "schema": { "type": "string", "format": "uuid" } } } } }