# API 网关接口对接文档 > 更新时间：2026-07-28 > 本文是一份快速对接教程，不替代在线接口定义。接口路径、字段、模型名称、状态值和返回数据均以在线接口文档、OpenAPI 数据及接口实际响应为准。 ## 1. 对接入口 | 项目 | 地址 | |---|------------------------------------------------------------------------------------------------------------------------------------------------| | 域名 | `http://gateway.domi-kids.com` | | 接口文档 | [https://doc.platform.domi-kids.com/](https://doc.gateway.domi-kids.com/) | | OpenAPI JSON | [http://test.gateway.domi-kids.com/domi/gateway/apifox/openapi/default](http://test.gateway.domi-kids.com/domi/gateway/apifox/openapi/default) | | Swagger | [http://test.gateway.domi-kids.com/gateway/swagger.html](http://test.gateway.domi-kids.com/gateway/swagger.html) | | API Key 管理后台 | [https://platform.domi-kids.com/](https://DomiAPI.domi-kids.com/) | 携带 API Key 时应优先使用 HTTPS。本文示例使用： - 域名：`https://gateway.domi-kids.com` 如果部署网络只能使用 HTTP，请先与网关负责人确认链路位于可信内网且传输风险可接受，不要通过公网明文传输 API Key。 ## 2. 获取 API Key 1. 由项目业务负责人说明项目、调用场景、环境和所需模型。 2. 联系任风、张潇或王勇中的任意一人开通 DomiAPI 平台账号。 3. 登录 [DomiAPI 管理后台](https://DomiAPI.domi-kids.com/)，创建或新增 API 密钥。 4. 确认密钥已获得所需模型权限和可用额度，再从测试环境开始联调。 请求统一使用以下鉴权格式： ```http Authorization: Bearer ``` 调用方只需要提供 DomiAPI API Key，不需要也不得提供 Seedance、Tripo 等供应商密钥。API Key 不应写入前端代码、Git、日志、错误信息或业务数据库。 ## 3. 接口范围 网关对外接口主要分为两类： | 类型 | 路径 | 说明 | |---|---|---| | OpenAI 兼容接口 | `/v1/**` | 透明转发到 DomiAPI，适合对话、Responses、Embedding、图片等能力 | | 供应商兼容接口 | `/domi/providers/{provider-code}/**` | 保留供应商原协议，适合视频、3D 等异步任务 | 常用能力如下： | 能力 | 主要接口 | |---|---| | 对话 | `POST /v1/chat/completions` | | Responses | `POST /v1/responses` | | 向量化 | `POST /v1/embeddings` | | Seedream 图片生成 | `POST /v1/images/generations` | | Seedance 视频任务 | `POST/GET /domi/providers/volcengine/api/v3/contents/generations/tasks...` | | Tripo 文生 3D、图生 3D、网格处理 | `/domi/providers/tripo/v3/**` | | Hi3D 图生 3D、浮雕 | `/domi/providers/hi3d/**` | | Meshy 文生 3D | `/domi/providers/meshy/**` | | Hyper3D 状态和结果查询 | `/domi/providers/hyper3d/**` | `/domi/gateway/internal/**` 是内部接口，普通业务方不得调用。其他供应商接口和详细字段请直接查阅在线接口文档。 ## 4. 公共请求要求 ### 4.1 必传 Header ```http Authorization: Bearer Content-Type: application/json domi-ai-metadata: {"schema_version":1,"business_request_id":"order-ai-0001","source_system_code":"crm","business_line_id":"sales"} ``` `domi-ai-metadata` 是网关业务归属元数据，必须是单行 JSON 字符串。网关校验后会将其删除，不会把该 Header 转发给 DomiAPI 或供应商。 最小字段说明： | 字段 | 必填 | 说明 | |---|---|---| | `schema_version` | 是 | 当前固定为整数 `1` | | `business_request_id` | 是 | 调用方业务请求 ID，建议在本项目内唯一，最长 128 字符 | | `source_system_code` | 是 | 已在网关启用的来源系统编码 | | `business_line_id` | 是 | 已在网关启用的业务线编码 | | `application_id` | 否 | 应用编码 | | `organization_id` | 否 | 机构编码 | | `user_id` | 否 | 业务用户 ID，不应放手机号、Token 等敏感信息 | | `classify` | 否 | 扩展分类键值，最多 20 项 | 示例中的 `crm` 和 `sales` 仅用于说明格式。实际调用前应向网关负责人取得本项目已启用的 `source_system_code` 和 `business_line_id`，否则请求会在连接上游前被拒绝。 浏览器原生 `EventSource` 无法设置 Header 时，可以将同名参数放入 URL Query 并进行 URL 编码；其他场景统一使用 Header。 ### 4.2 模型选择 聊天和图片模型可以通过以下接口实时查询： ```bash curl --request GET \ 'https://gateway.domi-kids.com/domi/gateway/api/model/names' ``` 典型返回结构： ```json { "chatModel": [ "deepseek-v4-flash", "deepseek-v4-pro" ], "imageModel": [ "doubao-seedream-4-5-251128", "doubao-seedream-5-0-260128" ] } ``` 该接口用于查看网关当前发布的聊天和图片模型。账号最终能否调用仍取决于 API Key 的模型权限和额度。视频、3D 的模型 ID 以对应接口文档中的请求 Schema、示例和接口实际响应为准。 ### 4.3 示例公共变量 以下示例均使用测试环境。请先替换 API Key、来源系统和业务线： ```bash export GATEWAY_BASE_URL='https://gateway.domi-kids.com' export DOMI_API_KEY='<替换为自己的 API Key>' export DOMI_AI_METADATA='{"schema_version":1,"business_request_id":"demo-20260728-0001","source_system_code":"crm","application_id":"demo-app","business_line_id":"sales","organization_id":"org-1001","user_id":"u-2001"}' ``` ## 5. 完整示例 ### 5.1 DeepSeek 对话 请求： ```bash curl --request POST \ "${GATEWAY_BASE_URL}/v1/chat/completions" \ --header "Authorization: Bearer ${DOMI_API_KEY}" \ --header "domi-ai-metadata: ${DOMI_AI_METADATA}" \ --header 'Content-Type: application/json' \ --data '{ "model": "deepseek-v4-flash", "messages": [ { "role": "system", "content": "你是一个简洁、准确的业务助手。" }, { "role": "user", "content": "用三点说明 API 网关的作用。" } ], "temperature": 0.2, "stream": false }' ``` 典型响应： ```json { "id": "chatcmpl-example", "object": "chat.completion", "model": "deepseek-v4-flash", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "1. 统一鉴权入口；2. 统一转发模型请求；3. 提供链路追踪和用量归集。" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 25, "completion_tokens": 35, "total_tokens": 60 } } ``` 如果需要 SSE 流式响应，将请求体中的 `stream` 改为 `true`，并增加： ```http Accept: text/event-stream ``` 客户端应逐段消费 `data:` 内容，直到收到 `data: [DONE]`，不要等待完整响应后再解析。 ### 5.2 Seedream 文生图 请求： ```bash curl --request POST \ "${GATEWAY_BASE_URL}/v1/images/generations" \ --header "Authorization: Bearer ${DOMI_API_KEY}" \ --header "domi-ai-metadata: ${DOMI_AI_METADATA}" \ --header 'Content-Type: application/json' \ --data '{ "model": "doubao-seedream-5-0-260128", "prompt": "一只戴着红色围巾的白色小猫站在雪地里，儿童绘本风格，柔和光线", "size": "1024x1024", "n": 1, "response_format": "url", "watermark": false }' ``` 典型响应： ```json { "created": 1785148800, "model": "doubao-seedream-5-0-260128", "data": [ { "url": "https://cdn.example.com/generated/image-1.jpeg", "size": "1024x1024" } ], "usage": { "generated_images": 1, "total_tokens": 4096 } } ``` 不同图片模型支持的尺寸、数量、返回格式、图生图和组图字段不同，不要把接口 Schema 中的全部可选字段一次性发送。返回 URL 通常有有效期，业务方应及时下载并保存到自己的存储。 ### 5.3 Seedance 2.0 Fast 文生视频 视频生成是异步任务。创建请求成功后先保存任务 ID，再调用查询接口获取终态。 创建任务： ```bash curl --request POST \ "${GATEWAY_BASE_URL}/domi/providers/volcengine/api/v3/contents/generations/tasks" \ --header "Authorization: Bearer ${DOMI_API_KEY}" \ --header "domi-ai-metadata: ${DOMI_AI_METADATA}" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: video-demo-20260728-0001' \ --data '{ "model": "doubao-seedance-2-0-fast-260128", "content": [ { "type": "text", "text": "清晨的森林中，一只白色小鹿从薄雾里缓慢走出，电影感运镜，柔和自然光" } ], "ratio": "16:9", "resolution": "720p", "duration": 5, "watermark": false }' ``` 创建成功响应： ```json { "id": "cgt-20260728123456-abcd" } ``` 查询任务： ```bash curl --request GET \ "${GATEWAY_BASE_URL}/domi/providers/volcengine/api/v3/contents/generations/tasks/cgt-20260728123456-abcd" \ --header "Authorization: Bearer ${DOMI_API_KEY}" \ --header "domi-ai-metadata: ${DOMI_AI_METADATA}" ``` 成功状态的典型响应： ```json { "id": "cgt-20260728123456-abcd", "model": "doubao-seedance-2-0-fast-260128", "status": "succeeded", "content": { "video_url": "https://cdn.example.com/result.mp4", "last_frame_url": "https://cdn.example.com/last-frame.jpg" }, "duration": 5, "resolution": "720p", "usage": { "completion_tokens": 49500, "total_tokens": 49500 } } ``` `status` 的完整取值以接口实际响应为准。未到终态时应间隔轮询，避免高频查询；成功后及时保存视频。创建请求网络结果不确定时，只能携带同一个 `Idempotency-Key` 重试，不要更换幂等键重复创建。 ### 5.4 Tripo 文生 3D 创建任务： ```bash curl --request POST \ "${GATEWAY_BASE_URL}/domi/providers/tripo/v3/generation/text-to-model" \ --header "Authorization: Bearer ${DOMI_API_KEY}" \ --header "domi-ai-metadata: ${DOMI_AI_METADATA}" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: tripo-demo-20260728-0001' \ --data '{ "prompt": "A production-ready stylized robot gardener, full body, clean topology", "model": "v3.1-20260211", "face_limit": 10000, "texture": true, "pbr": true, "texture_quality": "detailed" }' ``` 创建成功响应： ```json { "code": 0, "data": { "task_id": "task_abc123" } } ``` 查询任务： ```bash curl --request GET \ "${GATEWAY_BASE_URL}/domi/providers/tripo/v3/tasks/task_abc123" \ --header "Authorization: Bearer ${DOMI_API_KEY}" \ --header "domi-ai-metadata: ${DOMI_AI_METADATA}" ``` 成功状态的典型响应： ```json { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.example.com/task_abc123/model.glb", "rendered_image_url": "https://cdn.example.com/task_abc123/preview.webp" } } } ``` Tripo 接口保留供应商的 `code/data/message` 响应结构。模型版本、面数、纹理、PBR 和输出字段会随 Tripo 协议变化，应以当前接口文档为准。 ## 6. 异步任务对接建议 Seedance、Tripo、Hi3D、Meshy 等创建接口通常遵循以下流程： 1. 为每次业务创建生成稳定且唯一的 `Idempotency-Key`。 2. 发起创建请求并持久化供应商返回的 `task_id` 或 `id`。 3. 以有界频率查询任务，不要由每个前端页面高频直连轮询。 4. 识别供应商定义的成功、失败和处理中状态；未知状态不要直接判定失败。 5. 成功后及时保存结果文件；失败任务不应盲目重新创建。 不同供应商的任务 ID 字段、状态名称和结果结构不会被强行统一，必须分别按对应接口文档处理。 ## 7. 常见错误 | HTTP 状态或错误码 | 常见原因 | 处理建议 | |---|---|---| | `400 AI_METADATA_REQUIRED` | 未传 `domi-ai-metadata` | 补充必传 Header | | `400 AI_METADATA_INVALID` | JSON、版本、字段类型或必填字段错误 | 按元数据 Schema 修正 | | `400 UNSUPPORTED_SOURCE_SYSTEM_CODE` | 来源系统未登记或未启用 | 联系网关负责人配置 | | `400 UNSUPPORTED_BUSINESS_LINE_ID` | 业务线未登记或未启用 | 联系网关负责人配置 | | `400 BILLING_MODEL_NOT_RESOLVED` | 视频/3D 模型未配置或模型字段不匹配 | 使用接口文档中当前启用的模型 | | `401` | API Key 缺失、格式错误、无效或已停用 | 检查 `Bearer` 格式及后台状态 | | `404 PROVIDER_ROUTE_NOT_FOUND` | 供应商路径不在开放清单 | 对照 OpenAPI 检查路径 | | `429` | DomiAPI 或供应商限流、额度不足 | 降低并发，检查额度；按响应建议退避 | | `502` | DomiAPI 或供应商连接失败 | 记录请求 ID，有限重试可安全重试的请求 | | `503` | 网关过载或供应商未配置 | 退避后重试并联系网关负责人 | | `504` | 上游超时 | 查询异步任务状态，避免直接重复创建 | 网关会尽量保留 DomiAPI 或供应商原始错误。排障时请记录 HTTP 状态、响应错误码、`X-Domi-Request-Id` 以及上游返回的请求 ID，但不要记录 API Key、完整业务请求体或带签名的结果 URL。 ## 8. 上线前检查 - 已使用测试环境和目标 API Key 完成真实模型调用。 - `source_system_code`、`business_line_id` 已登记并启用。 - 模型名称来自实时模型接口或当前接口文档，没有写死已下线模型。 - API Key 只保存在服务端 Secret 或受控配置中。 - 对话 SSE 使用流式读取；图片、视频和 3D 文件及时转存。 - 异步创建请求使用稳定的 `Idempotency-Key`，查询任务有退避和最大时长。 - 客户端设置了合理的连接、读取和总超时，不对非幂等请求自动重试。 - 日志中不包含 Authorization、Cookie、完整 Prompt、图片/视频内容或供应商凭证。