文档中心 - 智予token工厂

快速接入

使用客户所属的 API 令牌调用 Stargate 下游接口。本文描述网关 main 分支的实际实现，不将后台管理接口、上游接口或尚未接通的路由当作可用能力。

先取得实际的网关根地址和 API 令牌，并完成该部署要求的客户认证。官网地址、控制台登录地址不等于模型调用地址。
先调用 GET /v1/models 获取当前令牌可见的模型 ID，再与服务方确认该模型支持的接口和参数。模型可见不代表所有能力都可调用。
示例中的 YOUR_*、task_EXAMPLE、模型和响应内容均为占位或结构示例，不是已上线模型、真实任务或调用结果。请替换后再执行。
以下命令使用 Bash / cURL 语法。STARGATE_BASE_URL 不带末尾斜杠，也不预先附加 /v1；若客户端会自动添加接口路径，请避免重复拼接 /v1。
只在可信服务端保存令牌；不要把真实令牌写进浏览器前端代码、公开仓库或截图。

设置本地环境变量（占位值）Bash / cURL

export STARGATE_BASE_URL="https://YOUR_GATEWAY_HOST"
export STARGATE_API_KEY="YOUR_API_KEY"

1. 获取可见模型Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/models" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

2. 发起文本对话Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_CHAT_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "你好，请用一句话介绍自己。"
    }
  ],
  "stream": false
}'

认证方式与权限

本文列出的模型、任务和兼容账务接口使用 API 令牌鉴权，而不是控制台登录会话。推荐发送 Authorization: Bearer YOUR_API_KEY。

也接受 x-api-key 请求头，但仅在 Authorization 中没有取得令牌时使用。不要同时发送两套不同的凭据。
令牌必须有效、启用且未过期；客户状态、客户认证、成员状态、IP / 子网限制及可访问模型限制也会影响请求。
客户归属由令牌解析，不能靠在请求中传入客户 ID 切换。服务令牌归属客户；成员令牌还关联具体成员。
任务查询按客户隔离；成员令牌进一步限制为该成员的任务。知道 task_id 并不等于有权限读取。
JSON 请求设置 Content-Type: application/json；音频文件上传使用 multipart/form-data，由 cURL 自动生成 boundary。
请求频率、并发、余额及可用模型取决于实际客户和路由配置。没有一个适用于所有客户的固定 QPS、重试次数或模型清单。

请求头HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

模型发现

模型列表受令牌 / 成员权限、分组和模型目录可见性影响。返回值不是全平台模型目录，也不包含完整的能力、价格或实时健康保证。

GET/v1/models列出可见模型

无请求体。返回 object: list 和 data 数组，另有 success、message 字段。

请求参数或响应字段说明
字段	类型 / 说明
`data[].id`string	调用时使用的模型 ID。
`data[].object / owned_by / created / root / parent`模型元数据	兼容元数据；不要把 owned_by 或 created 当成上游来源或模型上线时间的审计证据。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/models" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

响应结构（仅展示关键字段）JSON · 结构示例，非实测结果

{
  "success": true,
  "message": "",
  "object": "list",
  "data": [
    {
      "id": "YOUR_CHAT_MODEL_ID",
      "object": "model"
    }
  ]
}

GET/v1/models/:model查询单个可见模型

路径中的 :model 替换为模型 ID，返回单个模型对象。

本基线中，找不到模型时仍可能返回 HTTP 200，但响应体含 error.code: model_not_found。不能只判断 HTTP 状态码。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/models/YOUR_MODEL_ID" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

文本与对话

Chat Completions、Messages 和 Responses 是不同协议，消息结构、工具调用和流式事件不能混用。可选字段能否生效取决于目标模型和适配器，不承诺所有厂商参数无损互通。

POST/v1/chat/completionsChat Completions

JSON 请求；model 和非空 messages 必填。普通响应使用 choices，流式响应使用 SSE。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`messages`array · 必填	对话消息；常用元素为 { role: "user", content: "..." }。图片、工具消息等需要模型和适配器支持。
`stream`boolean · 可选	默认 false；true 时按 SSE 逐块读取，不能把整个响应当一个 JSON。
`max_tokens / max_completion_tokens`integer · 可选	输出长度参数，支持范围由模型决定；不要将它们与 Responses 的 max_output_tokens 混用。
`temperature / top_p / tools / tool_choice / response_format`可选	按目标模型的能力使用，不是全模型通用能力保证。

常见非流式文本位于 choices[].message.content；工具调用可能没有普通文本。常见流式增量位于 choices[].delta。不要用流式分块数量计算 Token 用量。

流式请求Bash / cURL

curl -sS -N "${STARGATE_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_CHAT_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "你好，请用一句话介绍自己。"
    }
  ],
  "stream": true
}'

POST/v1/messagesMessages 协议

接收 Messages 格式。网关校验 model、非空 messages，以及大于 0 的 max_tokens。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`messages`array · 必填	用户 / 助手消息，content 可为文本或协议内容块。
`max_tokens`integer · 必填	必须大于 0。
`system / stream / tools / thinking`可选	顶层 system、流式开关和扩展能力按该协议及目标适配器处理。

非流式响应使用 content 内容块；流式采用该协议的事件，不是 Chat Completions 的 choices[].delta。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/messages" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_MESSAGES_MODEL_ID",
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}'

POST/v1/responsesResponses 协议

接收 model、input 和 Responses 扩展字段。input 可为文本或输入项数组；响应读取 output，不应套用 Chat Completions 解析器。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`input`string \| array	输入文本或协议输入项。
`instructions / previous_response_id / tools`可选	指令、续接上下文和工具字段；实际续接、存储和工具行为由上游及适配器决定。
`stream / max_output_tokens / reasoning`可选	SSE 开关、输出长度和推理配置；部分适配器会转换或移除不支持的字段。

这里没有承诺 GET /v1/responses/:id 或 DELETE /v1/responses/:id；main 没有注册这些下游路由。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/responses" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_RESPONSES_MODEL_ID",
  "input": "你好，请简要介绍自己。",
  "stream": false
}'

POST/v1/responses/compactResponses 压缩

独立的 Responses 压缩入口，走 Responses 请求处理链；需要上游支持 compact，不是任意聊天模型的通用压缩服务。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`input`array	需要压缩的 Responses 上下文输入项。

按上游返回的压缩结果继续处理，不假定它返回聊天文本；此示例不启用 stream。

请求模板Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/responses/compact" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_COMPACT_MODEL_ID",
  "input": [
    {
      "role": "user",
      "content": "需要保留的对话上下文"
    }
  ]
}'

POST/v1/completions传统文本补全

model 和 prompt 必填；这是传统补全协议，不是 messages 对话协议。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`prompt`string \| array	要补全的提示内容；示例使用字符串。
`stream / max_tokens`可选	流式开关与输出限制，依模型支持情况使用。

响应通常从 choices[].text 读取；只能使用支持传统补全的模型。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/completions" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_COMPLETION_MODEL_ID",
  "prompt": "请续写：人工智能可以",
  "max_tokens": 128
}'

POST/v1/moderations内容审核兼容入口

已注册并走文本转发链，接收 model 和 input；它不代表平台保证对所有输入提供统一审核结果。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`input`string \| array	待审核输入。

本基线仍经过 text_generation 能力 / 文本计费校验，需服务方确认配置及上游支持。显式传 model，避免鉴权与转发阶段不同默认模型造成歧义。响应按实际审核协议读取。

向量嵌入

向量接口有独立的请求校验和计费处理。输出维度、批量限制和编码形式由实际模型决定；重排序接口的当前限制见“兼容边界”。

POST/v1/embeddings生成向量

model 和 input 必填。兼容路径可从 :model 读取模型；推荐使用 /v1/embeddings 并在 JSON 中明确模型。

同方法兼容路径/v1/engines/:model/embeddings

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`input`string \| array · 必填	文本或模型支持的批量输入格式。
`encoding_format / dimensions / user`可选	编码格式、输出维度和用户标识，实际支持依模型而定。

按实际响应读取 data[].embedding、data[].index 和 usage，不假定所有向量模型维度相同。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/embeddings" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_EMBEDDING_MODEL_ID",
  "input": [
    "知识库中的第一段文本",
    "知识库中的第二段文本"
  ]
}'

图像生成

标准图像生成与 DashScope 原生 / 异步图像接口分开提供。图片编辑和变体虽有路由，但本基线存在转发缺口，见“兼容边界”。

POST/v1/images/generations标准图像生成

使用 JSON 请求，同步返回图像响应；prompt 必填。不要把它当成返回 task_id 的异步任务接口。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`prompt`string · 必填	图像描述。
`n / size`integer / string · 可选	网关默认 n=1、size=1024x1024。数量和尺寸仍需满足具体模型约束。
`quality / style / response_format / user`可选	由模型和适配器支持；结果可能是 URL 或 Base64。

未传 model 时网关默认 dall-e-2，但这不代表该模型已对你的令牌开通，建议总是显式传入。
响应读取 data[].url 或 data[].b64_json；不要强制假定所有模型都返回公开 URL。图像尺寸、数量和定价配置不合法时请求会被拒绝。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_IMAGE_MODEL_ID",
  "prompt": "一只在窗边晒太阳的猫",
  "n": 1,
  "size": "1024x1024"
}'

音频接口

音频合成使用 JSON，转录 / 翻译使用文件表单。响应可能是 JSON、文本、字幕或二进制音频，不能统一调用 JSON 解析。

POST/v1/audio/speech语音合成

提供 model、input、voice；可传 speed 和 response_format。成功响应是音频内容，应保存为文件。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`input`string	待合成文本。main 使用 Go len(input) 校验上限 4096，即 UTF-8 字节数，不是 4096 个汉字。
`voice`string	使用目标模型实际支持的音色名称。
`speed / response_format`可选	速度与格式依模型支持；示例使用 mp3。

下载前检查 HTTP 状态和 Content-Type，避免将错误 JSON 当成音频文件。

请求（替换音色后执行）Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/audio/speech" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_TTS_MODEL_ID",
  "input": "你好，欢迎使用。",
  "voice": "YOUR_VOICE",
  "response_format": "mp3"
}' \
  --output speech.mp3

POST/v1/audio/transcriptions语音转录

上传音频文件，返回识别内容。文件类型、大小与语言支持由目标模型决定。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`file`file · multipart	本地音频文件。
`response_format`string · 可选	网关处理 json、text、srt、verbose_json、vtt；具体模型不一定全部支持。

不要手工添加不含 boundary 的 multipart Content-Type。省略 model 时默认 whisper-1，不表示已开通该模型。

文件上传Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/audio/transcriptions" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -F "model=YOUR_TRANSCRIPTION_MODEL_ID" \
  -F "file=@sample.wav" \
  -F "response_format=json"

POST/v1/audio/translations音频翻译

使用与转录相同的 multipart 文件上传方式，将路径改为 /v1/audio/translations，并选择支持音频翻译的模型。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`file / response_format`multipart 表单	与转录接口相同；输出语言和格式取决于目标模型。

这不是任意语言互译或实时语音 WebSocket 接口。

视频异步任务

提交 → 保存 task_id → 查询状态 → 完成后下载。接受请求与生成成功是两个阶段；必须读取任务最终状态。

视频状态为 queued、in_progress、completed、failed、cancelled、expired；unknown 表示未识别状态，不是成功。
视频任务 ID 是网关返回的 task_...，不要替换为上游任务 ID。服务令牌按客户读取，成员令牌只读取该成员任务。
视频提交不自动执行跨渠道失败重试。若超时或返回恢复中信息，先核查已有任务，避免重复提交造成重复生成或扣费。
若响应 metadata.recovery_status 为 pending，请保留任务 ID 继续核查；不能将它当作生成完成。轮询应设置间隔与截止时间，不要无限高频请求。

POST/v1/videos提交视频生成

仅使用 JSON 请求。网关返回 HTTP 202 和 object: video，不直接返回视频文件。

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`prompt`string	文本提示；某些支持媒体输入的模型可使用有效 metadata.content 代替，具体输入组合由适配器校验。
`seconds`string \| number · 可选	时长，网关接受字符串或数字并转换为内部时长字段；范围依模型。
`size / input_reference`string · 可选	尺寸 / 分辨率与参考输入，语义和支持范围依目标模型。
`metadata`object · 可选	模型特有参数和媒体内容；不是任意参数均被所有模型支持。
`callback_url`string · 可选	任务终态回调地址，需满足网关 URL 安全校验；回调细节见下一节。

模型可能还要求时长、比例或其他 metadata 字段，请按实际开通的模型补齐。不能把某一个视频模型的参数范围当成统一网关约束。

最小提交模板Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/videos" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_VIDEO_MODEL_ID",
  "prompt": "一只猫沿着窗台缓慢行走"
}'

202 响应结构（关键字段）JSON · 结构示例，非实测结果

{
  "id": "task_EXAMPLE",
  "object": "video",
  "model": "YOUR_VIDEO_MODEL_ID",
  "status": "queued",
  "progress": 0
}

GET/v1/videos列出视频任务

返回 { object: "list", data: [...] }。只读取当前权限范围内的任务。

请求参数或响应字段说明
字段	类型 / 说明
`limit`query · integer	默认 20，范围 1–500。main 此接口没有实现 page、after、before 等游标参数。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/videos?limit=20" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

GET/v1/videos/:id查询视频状态

读取 / 刷新任务，返回 id、object、model、status、progress；完成时可包含 result_url，失败时可包含 error。

仅 status=completed 表示生成完成。result_url 是网关内容地址，仍需鉴权；不可直接当作匿名公开链接。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/videos/task_EXAMPLE" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

GET/v1/videos/:id/content下载视频内容

任务 completed 后代理输出二进制视频内容，支持转发 Range / If-Range 请求头。尚未完成返回 409 video_not_ready。

请求参数或响应字段说明
字段	类型 / 说明
`index`query · integer · 可选	多结果时使用，从 0 开始，默认 0；越界返回 404。

浏览器 video 标签无法直接附加 Bearer 请求头，业务端应自行设计受控的内容获取方式，不要把 API Key 放进 URL。下载时仍需检查错误状态和 Content-Type。

下载（先确认任务已完成）Bash / cURL

curl -sS "${STARGATE_BASE_URL}/v1/videos/task_EXAMPLE/content" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  --output video.mp4

POST/v1/videos/:id/cancel取消视频任务

无请求体。对非终态任务调用上游取消能力；对已终态任务返回当前状态，不保证所有模型都支持中途取消。

请求Bash / cURL

curl -sS -X POST "${STARGATE_BASE_URL}/v1/videos/task_EXAMPLE/cancel" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

DELETE/v1/videos/:id删除视频任务

与取消不同，且要求上游支持删除。成功返回 id、object: video.deleted、deleted: true。

queued：请求上游删除并转为取消；completed / failed / expired：上游删除成功后软删除本地任务；in_progress / cancelled：不支持删除，返回 409。实际操作还会复核上游状态。
删除任务不是删除账务或审计记录，也不应被理解为自动退款。

DashScope 图像接口

路径以 /dashscope 开头，不是 /v1/dashscope。以下原生格式与标准 /v1/images/generations 不同，需选用支持该协议的模型和适配器。

POST/dashscope/api/v1/services/aigc/multimodal-generation/generation多模态图像生成（同步）

接收 model、input.messages[].content 和 parameters，按原生图像协议处理并返回结果，不采用异步 task_id 查询流程。

同方法兼容路径/dashscope/multimodal-generation/generation

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`input.messages[].content`array	文本块 { text: "..." }，需要时加入模型支持的图片内容块。
`parameters`object · 可选	例如 n、size；尺寸和输入组合由模型约束。

读取原生响应 output（例如 output.choices 中的图片内容），不要强制套用标准图像 data[]。该入口不自动跨渠道重试。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/dashscope/api/v1/services/aigc/multimodal-generation/generation" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_DASHSCOPE_IMAGE_MODEL_ID",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "text": "一只在窗边晒太阳的猫"
          }
        ]
      }
    ]
  },
  "parameters": {
    "n": 1
  }
}'

POST/dashscope/api/v1/services/aigc/image-generation/generation创建异步图像任务

model 和 input.messages 中的非空文本提示必填。返回 HTTP 200，output.task_id 是网关任务 ID，初始 output.task_status 为 PENDING。

同方法兼容路径/dashscope/image-generation/generation

请求参数或响应字段说明
字段	类型 / 说明
`model`string	填写当前令牌可见、且已开通相应能力的模型 ID；不是模型展示名称。
`input.messages[].content[].text`string · 必需文本提示	网关会提取并合并文本；不要直接沿用其他接口的顶层 prompt。
`parameters / callback_url`可选	模型参数与终态回调地址。

HTTP 200 仅表示提交响应成功，必须继续查询任务状态。此路径本身选择异步任务流程，不通过额外的异步请求头切换；网关不自动跨渠道重试。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/dashscope/api/v1/services/aigc/image-generation/generation" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_DASHSCOPE_IMAGE_MODEL_ID",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "text": "一只在窗边晒太阳的猫"
          }
        ]
      }
    ]
  },
  "parameters": {
    "n": 1
  }
}'

200 响应结构（关键字段）JSON · 结构示例，非实测结果

{
  "request_id": "task_EXAMPLE",
  "output": {
    "task_id": "task_EXAMPLE",
    "task_status": "PENDING"
  }
}

GET/dashscope/api/v1/tasks/:id查询图像任务

读取 output.task_status：PENDING、RUNNING、SUCCEEDED、FAILED、CANCELED、UNKNOWN。只有 SUCCEEDED 表示生成成功。

同方法兼容路径/dashscope/tasks/:id

完成后从 output.results[].url 或 output.choices[].message.content[].image 读取图片。失败信息可能在 output.code / output.message。查询接口错误也可能是顶层 code / message，不总是 error 对象。
此处的 CANCELED 与视频接口 cancelled 拼写不同。UNKNOWN 也用于无法映射的状态，不能作为成功处理。

请求Bash / cURL

curl -sS "${STARGATE_BASE_URL}/dashscope/api/v1/tasks/task_EXAMPLE" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

POST/dashscope/api/v1/tasks/:id/cancel取消图像任务

无请求体；返回当前任务的原生格式状态。实际能否取消取决于上游支持；已终态任务返回当前状态。

同方法兼容路径/dashscope/tasks/:id/cancel

请求Bash / cURL

curl -sS -X POST "${STARGATE_BASE_URL}/dashscope/api/v1/tasks/task_EXAMPLE/cancel" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

任务回调

视频和 DashScope 异步图像请求可带 callback_url。网关在任务终态后向该地址发送 JSON POST；回调不是逐帧 / 逐进度通知。建议始终保留查询接口作为核对方式。

接收方应返回 2xx。投递失败可能被重试，请按任务 ID 和终态做幂等处理，避免重复执行下游业务。
回调是网关自己的结构：id、object、model、status、progress，以及可选 result_url、result_urls、error。视频 object 为 video，图像为 image.task。
回调使用内部任务状态，终态为 completed、failed、cancelled、expired。图像回调的 completed 不等于查询响应中的字面值 SUCCEEDED，需分别解析。
callback_url 必须是网关允许访问的 HTTP(S) 地址，受 URL / 地址安全校验限制。不要假定 localhost 或内网地址可作为回调。
仅在部署配置了回调签名密钥时，才带 X-Stargate-Timestamp 和 X-Stargate-Signature。签名为 sha256= 加 HMAC-SHA256 的十六进制摘要，待签名内容为毫秒时间戳 + "." + 原始请求体。
签名密钥不是 API Key，也不是请求参数。接收前应与服务方确认签名配置和验签方式，校验时间窗与重复投递；未配置签名时，不要仅凭公网回调内容认定任务成功，可再用鉴权查询核实。

回调结构（关键字段）JSON · 结构示例，非实测结果

{
  "id": "task_EXAMPLE",
  "object": "video",
  "model": "YOUR_VIDEO_MODEL_ID",
  "status": "completed",
  "progress": 100,
  "result_url": "/v1/videos/task_EXAMPLE/content"
}

用量与计费

生成接口的 usage、客户累计用量和实际费用不是同一个量。文本可能采用上游 usage 或网关估算；图像、音频、视频还依赖各自的定价配置，不可统一按文本 Token 换算。

两个兼容账务查询都要求成员令牌，并且同时具有 wallet.read 和 usage.read_all 权限；服务令牌不允许查询，返回 403 subject_billing_read_denied。
统计范围是令牌所属客户，而不是当前单个令牌。main 的 usage 查询不读取 start_date / end_date，不能靠这些参数获取指定日期账单。
金额换算依赖部署配置 DisplayInCurrencyEnabled 和 QuotaPerUnit。字段名带 usd 不保证是美元金额；不能把 total_usage 当 Token 数。
本文不承诺不存在的项目 / 空间账单、按日周月导出或预算告警 API。实际费用以客户用量与结算记录为准。

GET/dashboard/billing/subscription查询兼容额度信息

返回 object: billing_subscription。soft_limit_usd、hard_limit_usd、system_hard_limit_usd 都由“客户钱包剩余额度 + 客户累计已用额度”换算而来，不是余额本身。

同方法兼容路径/v1/dashboard/billing/subscription

请求参数或响应字段说明
字段	类型 / 说明
`has_payment_method`boolean	实现固定为 true，不能用它判断是否绑定了支付方式。
`access_until`integer	直接取令牌过期时间；本项目令牌时间戳为毫秒，非正值归零，不应按常见秒时间戳直接解释。

部分内部查询错误返回 HTTP 200 + error 对象，仍需检查响应体。

请求（需账务权限）Bash / cURL

curl -sS "${STARGATE_BASE_URL}/dashboard/billing/subscription" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

GET/dashboard/billing/usage查询客户累计用量

返回 { object: "list", total_usage: ... }。total_usage 是客户累计消耗按部署显示单位换算后乘以 100，不是原始 Token 数，也不是日期区间账单。

同方法兼容路径/v1/dashboard/billing/usage

同样需要同时检查 HTTP 状态与响应体 error，且需具备客户认证和账务读取权限。

请求（需账务权限）Bash / cURL

curl -sS "${STARGATE_BASE_URL}/dashboard/billing/usage" \
  -H "Authorization: Bearer ${STARGATE_API_KEY}"

错误与重试

先看 HTTP 状态，再看响应体和任务终态。同步调用、SSE、二进制下载、视频任务与 DashScope 任务分别解析，不存在一种覆盖所有接口的统一响应格式。

网关会生成 x-request-id 响应头，部分错误消息还会附带请求 ID。提交问题时不要提供完整 API Key。
流式连接中断并不等于上游未执行；客户端应设置超时与有界重试，不能承诺重试不会产生额外调用。
DashScope 查询 / 取消的错误可能使用顶层 code、message；任务本身失败也可能仍是 HTTP 200，必须读取任务状态。

常见错误结构JSON · 结构示例，非实测结果

{
  "error": {
    "message": "错误说明",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

常见 HTTP 状态与处理方式
状态	含义	处理建议
400	请求格式、参数、模型能力或计费配置不匹配	检查 JSON / multipart、必填参数及 model_capability_unsupported 等错误码。
401	未提供、无效、禁用或过期的令牌	检查实际发送的鉴权头；不要重试同一个失效凭据。
403	客户认证、IP、成员 / 账务权限或模型调用被禁用	例如 subject_verification_required、subject_billing_read_denied、model_call_disabled；修正权限 / 状态。
404	模型不可用、任务不可见或路径错误	检查模型 ID、任务所属客户 / 成员和接口路径。模型详情另有 200 + error 的兼容行为。
409	任务未完成或当前状态不允许操作	例如 video_not_ready、task_delete_not_supported；读取任务状态后再决定。
429	频率、并发或路由排队限制	降低并发，设置有上限的退避；不假定总会有 Retry-After 请求头。
501	明确未实现的兼容接口	api_not_implemented；不要通过重试尝试启用功能。
5xx	上游、转发、存储或网关暂时故障	保留 x-request-id、时间和脱敏请求。异步提交结果不明时先核查任务，避免重复生成。

兼容边界

路由存在不等于能力已接通。以下结论以本页标注的 main 提交为准；不将开发分支、历史说明或上游原厂的完整 API 列表作为当前服务承诺。

已注册但存在转发缺口

POST /v1/rerank

已注册，但 main 的 Rerank 转发分支为空，没有调用重排序处理器。不能视为已完成的可用重排序 API。

POST /v1/images/edits

已注册，但公共转发分派没有进入图片编辑处理器，而落入文本 JSON 处理链；不能按标准 multipart 图片编辑接口接入。

POST /v1/images/variations

与图片编辑相同，公共转发分派未接通图片变体处理器；本文不提供声称可运行的成功示例。

明确未实现：501

以下路由通过鉴权后返回 api_not_implemented。文件管理未实现，不等于音频接口不能上传文件；两者是不同接口。

旧版文本编辑 / 模型删除 2 条路由

POST /v1/edits
DELETE /v1/models/:model

Files 文件管理 5 条路由

GET /v1/files
POST /v1/files
DELETE /v1/files/:id
GET /v1/files/:id
GET /v1/files/:id/content

Fine-tuning 微调 5 条路由

POST /v1/fine_tuning/jobs
GET /v1/fine_tuning/jobs
GET /v1/fine_tuning/jobs/:id
POST /v1/fine_tuning/jobs/:id/cancel
GET /v1/fine_tuning/jobs/:id/events

Assistants 助手与文件 9 条路由

POST /v1/assistants
GET /v1/assistants/:id
POST /v1/assistants/:id
DELETE /v1/assistants/:id
GET /v1/assistants
POST /v1/assistants/:id/files
GET /v1/assistants/:id/files/:fileId
DELETE /v1/assistants/:id/files/:fileId
GET /v1/assistants/:id/files

Threads / Messages / Runs 17 条路由

POST /v1/threads
GET /v1/threads/:id
POST /v1/threads/:id
DELETE /v1/threads/:id
POST /v1/threads/:id/messages
GET /v1/threads/:id/messages/:messageId
POST /v1/threads/:id/messages/:messageId
GET /v1/threads/:id/messages/:messageId/files/:filesId
GET /v1/threads/:id/messages/:messageId/files
POST /v1/threads/:id/runs
GET /v1/threads/:id/runs/:runsId
POST /v1/threads/:id/runs/:runsId
GET /v1/threads/:id/runs
POST /v1/threads/:id/runs/:runsId/submit_tool_outputs
POST /v1/threads/:id/runs/:runsId/cancel
GET /v1/threads/:id/runs/:runsId/steps/:stepId
GET /v1/threads/:id/runs/:runsId/steps

本基线没有注册的常见路径

/v1/contents/generations/tasks
/volces/…
/dawoai/volces/…
/v1/dashscope/…
GET /v1/responses/:id
DELETE /v1/responses/:id
/v1/realtime

不要将上游厂商地址、历史 Volces 接口说明或控制台 /api/… 管理路由直接用作下游模型 API。

常见问题

是否需要分别对接每个模型厂商？

可以通过网关统一鉴权和地址接入，但仍需选择对应协议。Chat Completions、Messages、Responses、DashScope 和异步任务并不是相同的请求 / 响应格式。

为什么模型出现在列表里却调用失败？

目录可见性、调用开关、模型能力、客户权限、余额、路由可用性和上游状态分别校验。GET /v1/models 不会替你完成一次真实模型调用。

能否在请求中指定备用供应商和统一重试策略？

普通下游调用按 model 及客户配置进行路由，本文没有提供客户端任意配置后台路由的 API。视频与 DashScope 图像提交在 main 中不会自动跨渠道重试。

为什么账务接口的数值与我理解的 Token 数不同？

它返回客户级累计额度的兼容换算值，而不是单个令牌的原始 Token 数。还需结合显示单位、QuotaPerUnit 和实际定价理解。

文档是否表示所有示例已在生产环境实测？

不是。本页依据标注版本的源代码整理；示例是请求模板与结构示例。具体域名、模型开通、价格和运行可用性仍由实际部署决定。

Resources

下载中心

获取模型接入所需的操作指引与接口参考文件，下载后即可开始配置和联调。

DOCX

WorkBuddy 接入指引

从模型选择、渠道配置到调用验证的完整接入说明。

下载文件

ZIP

MiniMax H3 接入 API 文档

包含接口说明、请求示例和视频生成客户端参考代码。

下载文件