Gate API 文档

概述

Gate 对外统一暴露 model_group 名称，路由与执行由 Gate 平台统一处理，调用方无需感知底层实现。

export GATE_BASE_URL="https://api-gate.astralmindai.com"
export GATE_API_KEY="sk-..."

1. 基础信息

1.1 Base URL

不同环境域名以实际部署为准。

https://api-gate.astralmindai.com

1.2 鉴权方式

• 除公开模型列表外，模型调用接口都需要 API Key。
• 推荐：Authorization: Bearer <GATE_API_KEY>
• 兼容：x-api-key: <GATE_API_KEY>

1.3 通用请求头

Content-Type: application/json
Authorization: Bearer <GATE_API_KEY>

1.4 模型名称

请求里的 model 即 model_group，例如 deepseek-v4-flash、nano-banana-2、seedance-2.0-fast。

1.5 查询可用模型

公开接口，不需要 API Key。

curl -X GET "$GATE_BASE_URL/public/model_group/info" \
  -H "accept: application/json"

指定模型：

curl -X GET "$GATE_BASE_URL/public/model_group/info?model_group=deepseek-v4-flash" \
  -H "accept: application/json"

也可在 模型市场 浏览各模型详情与 Playground。

2. 同步对话

兼容标准 Chat Completions 协议。

2.1 接口地址

POST /v1/chat/completions

2.2 请求参数

• supported_openai_params 可通过 /public/model_group/info 查询。
• 不同模型对扩展参数支持不同，未支持参数可能被忽略或被拒绝。
• 多模态对话在 messages[].content 传标准 content array，需 supports_vision=true。

2.3 非流式请求示例

curl -X POST "$GATE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "用一句话介绍 Gate。"}
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "enable_thinking": false
  }'

2.4 非流式响应参数

{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "created": 1780000000,
  "model": "deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Gate 是一个统一管理和调用 AI 模型的网关平台。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 30,
    "total_tokens": 50
  }
}

2.5 流式请求示例

curl -N -X POST "$GATE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "写一个三行的海边短诗。"}
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

2.6 流式响应格式

响应为 SSE，逐行读取 data:，遇到 [DONE] 表示结束。

data: {"choices":[{"delta":{"content":"海"}}]}

data: {"choices":[{"delta":{"content":"风"}}]}

data: [DONE]

2.7 视觉对话示例

支持公网 URL 或 Base64 data URL（data:image/png;base64,...）。

curl -X POST "$GATE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-vl-plus",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请描述这张图。"},
          {
            "type": "image_url",
            "image_url": {"url": "https://example.com/demo.jpg"}
          }
        ]
      }
    ]
  }'

3. 图片生成/编辑

兼容标准 Images 协议，切换模型只改 model 字段。

3.1 接口地址

POST /v1/images/generations

3.2 通用请求参数

• model
• prompt
• n
• size
• response_format

3.3 模型专属参数

以 input_parameters JSON Schema 为准。传未声明参数可能被静默丢弃或被下游拒绝；降级后按新模型 Schema 重新过滤。

3.4 文生图示例

curl -X POST "$GATE_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "一只戴墨镜的猫，工作室灯光，摄影风格",
    "n": 1,
    "size": "1024x1024"
  }'

3.5 图生图/参考图编辑

curl -X POST "$GATE_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "把图1的服装换成蓝色",
    "image": "https://example.com/ref.png",
    "n": 1
  }'

3.6 返回响应格式

data[] 中返回 url 或 b64_json（部分 nano-banana 系列返回 b64_json，其余多为 url）。

3.7 计费说明

• 按张计费：n × 每张单价，部分模型单价随分辨率/质量浮动。
• 按 token 计费（如 gpt-image 系列）：按实际输入/输出 token 结算。

4. 异步视频生成

先 create_task 获得 task_id，再 get_result 轮询，或通过 callback_url 接收终态。参数以 input_parameters 为准。

4.1 创建任务

curl -X POST "$GATE_BASE_URL/api/multimodal/create_task" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "priority": 5,
    "inputs": [
      {
        "name": "prompt",
        "value": "一只橘猫在海边奔跑，夕阳逆光，电影感镜头",
        "format": "text"
      }
    ],
    "metadata": {
      "ratio": "16:9",
      "duration": 5,
      "resolution": "720p",
      "watermark": false,
      "generate_audio": true,
      "return_last_frame": true
    }
  }'

创建成功返回：

{"task_id": "1998d2f1-9122-48b9-a3ca-dbd157918174"}

4.2 请求参数

• model：必填，对外模型名称。
• inputs[]：prompt（text）、image_url（first_frame/last_frame/reference_image）、video_url、audio_url。
• metadata：ratio、duration、resolution、watermark、generate_audio、return_last_frame、safety_identifier、execution_expires_after、biz_id 等。
• priority：0～9，数值越大优先级越高。
• Seedance 2.0 系列不支持 seed、draft、frames、camera_fixed。
• 素材需公网可访问；图片最多 9 张、视频/音频各最多 3 个（2.5 系列上限更高，以 Schema 为准）。

4.3 多参考素材示例

curl -X POST "$GATE_BASE_URL/api/multimodal/create_task" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "priority": 8,
    "inputs": [
      {"name": "prompt", "value": "根据参考素材生成电影感广告", "format": "text"},
      {"name": "image_url", "value": "https://example.com/reference.jpg", "format": "reference_image"},
      {"name": "video_url", "value": "https://example.com/reference.mp4", "format": "reference_video"},
      {"name": "audio_url", "value": "https://example.com/reference.mp3", "format": "reference_audio"}
    ],
    "metadata": {
      "ratio": "1:1",
      "duration": 4,
      "resolution": "480p",
      "generate_audio": true,
      "biz_id": "order-001"
    },
    "callback_url": "https://example.com/gate/callback",
    "callback_secret": "replace-with-your-secret"
  }'

4.4 查询任务结果

curl -X POST "$GATE_BASE_URL/api/multimodal/get_result" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "taskId": "f41824a0-497e-407b-b66a-5b3eefaae769"
  }'

建议每 2～5 秒查询一次，长任务可逐步增加轮询间隔。

4.5 取消任务

curl -X POST "$GATE_BASE_URL/api/multimodal/cancel_task" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "taskId": "1998d2f1-9122-48b9-a3ca-dbd157918174"
  }'

• canceled=true 不代表一定已停止下游，以 provider_canceled 与后续 get_result 为准。
• 下游已开始生成时可能返回 409 cancel_not_allowed。

4.6 Callback 通知

• 创建任务时传 callback_url，终态 success/failed 后 POST JSON 通知。
• callback_secret 启用时请求头含 X-Fx-Signature: sha256=<HMAC-SHA256_HEX>。
• 按 taskId 幂等处理；仍建议保留 get_result 补偿查询。

5. 错误响应

5.1 统一错误格式

{
  "error": {
    "message": "Authentication Error, No api key passed in.",
    "type": "auth_error",
    "param": null,
    "code": "401"
  }
}

5.2 参数校验错误（422）

{
  "detail": [
    {"type": "missing", "loc": ["body", "model"], "msg": "Field required"}
  ]
}

5.3 常见状态码

• 401 auth_error：未传 Key 或 Key 过期
• 429 budget_exceeded / concurrent_limit_exceeded
• 422：请求体不符合 Schema
• 404 / 403 / 409：异步任务相关错误

5.4 预算超限示例

{
  "error": {
    "message": "Budget has been exceeded! Current cost: 2.5, Max budget: 0.25",
    "type": "budget_exceeded",
    "param": null,
    "code": "429"
  }
}

5.5 全链路 trace

请求头传入 x-trace-id 即可接入业务 trace。

6. 接入方重试建议

同步接口

• 非流式请求可在网络错误、超时、502/503 时重试。
• 流式请求若已收到部分内容，不建议无脑重试并拼接，需业务侧决定是否重新生成。

异步接口

• create_task 若未拿到 task_id，可用 metadata.biz_id 做业务幂等，避免重复提交失控。
• get_result 建议每 2～5 秒轮询，长任务逐步加大间隔。
• 接入 callback 后，仍建议保留 get_result 兜底查询。

7. Postman 快速导入

以下 curl 可直接导入 Postman。

7.1 查询模型列表

curl -X GET "$GATE_BASE_URL/public/model_group/info" \
  -H "accept: application/json"

7.2 同步对话

curl -X POST "$GATE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "用一句话介绍 Gate。"}
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "enable_thinking": false
  }'

7.3 同步流式对话

curl -N -X POST "$GATE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "写一个三行的海边短诗。"}
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

7.4 创建视频任务

curl -X POST "$GATE_BASE_URL/api/multimodal/create_task" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "priority": 8,
    "inputs": [
      {"name": "prompt", "value": "根据参考素材生成电影感广告", "format": "text"},
      {"name": "image_url", "value": "https://example.com/reference.jpg", "format": "reference_image"},
      {"name": "video_url", "value": "https://example.com/reference.mp4", "format": "reference_video"},
      {"name": "audio_url", "value": "https://example.com/reference.mp3", "format": "reference_audio"}
    ],
    "metadata": {
      "ratio": "1:1",
      "duration": 4,
      "resolution": "480p",
      "generate_audio": true,
      "biz_id": "order-001"
    },
    "callback_url": "https://example.com/gate/callback",
    "callback_secret": "replace-with-your-secret"
  }'

7.5 获取任务结果

curl -X POST "$GATE_BASE_URL/api/multimodal/get_result" \
  -H "Authorization: Bearer $GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "taskId": "f41824a0-497e-407b-b66a-5b3eefaae769"
  }'