接口参考

当前环境：

与 Portal 文档引导接口返回一致；生产示例见模型与价格页。

• 按 Token：输入 / 输出分别计价（见 模型与价格）
• 按次：图片等按调用次数
• 仅 HTTP 2xx 且业务成功后扣费；失败释放预扣

• 文生图（OpenAI 标准）：POST /v1/images/generations，JSON 仅 prompt 等；禁止 image_urls（返回 400）
• 图生图 / 关联生图（OpenAI 标准）：POST /v1/images/edits，multipart/form-data 上传 image（可多张），不传 mask；Grsai 线路在网关内适配为上游 generations + image[]
• 局部重绘（mask）：同上 edits 并上传 mask；仅 image_mask_enable=1 线路（如 Rivo）。Grsai 对 mask 返回 400
• 同步出图（默认）：不传 async、无 callbackUrl；HTTP 单次等待 { created, taskId, task_id, data[].b64_json }，taskId 为返回给下游查询用的网关任务 ID
• 异步出图：async=true 或 callbackUrl → 立即 { taskId, task_id, status: pending }，轮询 GET /v1/images/tasks/{taskId}
• 异步终态：任务完成后默认返回 { created, taskId, task_id, data[].url }；若任务仍在处理中，仅返回 taskId、task_id 与 status
• 任务执行：客户端异步是 Gateway 侧任务能力；上游同步/异步差异由 Gateway 内部适配

• 提交任务：POST /v1/videos，JSON 使用 Seedance 官方兼容字段，例如 prompt、duration、aspect_ratio、resolution、image_url、reference_images。
• 任务查询：提交后返回 Gateway 本地 vid-...，轮询 GET /v1/videos/{taskId}；查询也兼容部分上游任务 ID。
• 异步控制：async=true 或 callbackUrl 为 Gateway 扩展字段，只控制下游交互，不透传到 Seedance 官方上游。
• 成功结果：任务完成后按官方对外格式返回 { task_id, taskId, status, data[].video_url }；若上游返回临时链接，Gateway 会先上传到 COS，再保存并返回我们的 COS URL。
• 统一链路：视频任务与异步图片共用网关任务模板、COS 写入/读取逻辑和 callbackUrl 投递语义。

POST /v1/chat/completions 设 "stream": true 时返回 SSE（text/event-stream）。

• 响应为多条 data: {"object":"chat.completion.chunk",...}，末尾 data: [DONE]
• 网关对上游 chunk 原样转发（保留上游 id、model 及 finish_reason:null 等字段）
• 流式响应中不包含计费字段 billing；控制台请求日志中的 response_body 为台账 JSON，不能用来判断客户端实际收到的 SSE
• 可用 stream_options: {"include_usage": true}，usage chunk 由上游原样透出

POST /v1/images/generations、/v1/images/edits、/v1/videos 支持 callbackUrl 异步任务回传。

• 请求方式：网关向调用方传入的 callbackUrl 发起 POST，Body 为 JSON。
• 触发时机：图片 / 视频任务提交后接口立即返回 task_id；任务成功后投递，不等待回调接收方处理完成。
• 请求体：与对应任务查询成功响应一致，图片为 GET /v1/images/tasks/{taskId}，视频为 GET /v1/videos/{taskId}；顶层包含 task_id、taskId、status、data、usage 等字段。
• 幂等建议：接收方使用 task_id 去重；重复收到同一请求时返回成功即可。
• 接收约定：建议返回 HTTP 2xx 表示接收成功；非 2xx、超时或网络错误可能被视为投递失败。
• 安全建议：使用 HTTPS 私有回调地址，并在业务侧校验来源、路径随机串或自定义 token。

标准接口失败时返回 JSON：