接入文档

从拿到 API Key 到跑通第一个请求，以及全部协议端点与最佳实践。

快速开始

按以下四步，几分钟内即可完成首次调用：

步骤	说明
1. 获取 API Key	联系你的管理员在控制台「成员与 Key」中发放，一人一 Key
2. 选择模型	在模型广场选择模型并复制模型标识（如 `qwen/qwen3.8-27b`）
3. 替换参数	将示例中的 `<YOUR_API_KEY>` 替换为你的 Key，`model` 替换为模型标识，图片/音频地址替换为你自己可公网访问的链接
4. 执行请求	发送请求并查看响应结果

项目	值
基础地址 Base URL	`https://model-router.edu-aliyun.com`
认证方式	请求头 `Authorization: Bearer <YOUR_API_KEY>`
兼容协议	OpenAI · Anthropic
接口分类	8 类：文本对话 / 语音合成 / 语音理解 / 图片生成 / 视频生成 / 向量 / 排序 / 异步任务查询（多模态对话、全模态对话、图片编辑、图生视频为对应类目的细分场景，本文档单独拆节详述）

模型标识的写法

模型标识请从模型广场原样复制，两点常见疑问：

标识里的 ^ 是正常字符：它是网关对模型名中 / 的转义写法（因 / 已用作「渠道/模型」分隔符），例如 qwen/MiniMax^MiniMax-M3、qwen/kling^kling-v3-video-generation。请照原样传入 model 参数，不要手工改成 /，否则会报模型不存在。
响应里的 model 字段可能显示为解码后的名称：例如请求传 qwen/MiniMax^MiniMax-M3，响应可能回显 MiniMax/MiniMax-M3。这属网关的正常行为，不代表调用异常或命中了别的模型；做日志比对时请按此规则匹配。
带 /v1 后缀的标识（如 custom/kimi-k3/v1）是大客专属模型的版本消歧后缀，属于标识的一部分，复制时须一并带上，去掉会导致调用失败。

Python（openai SDK）

# pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_API_KEY>",
    base_url="https://model-router.edu-aliyun.com/v1",
)
resp = client.chat.completions.create(
    model="qwen/qwen3.8-27b",
    messages=[{"role": "user", "content": "你好，请介绍一下自己"}],
)
print(resp.choices[0].message.content)

Node.js（openai SDK）

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<YOUR_API_KEY>",
  baseURL: "https://model-router.edu-aliyun.com/v1",
});
const resp = await client.chat.completions.create({
  model: "qwen/qwen3.8-27b",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

curl（文本对话）

curl -X POST https://model-router.edu-aliyun.com/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3.8-27b",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "你好，请介绍一下自己"}
  ]
}'

文本对话

聊天补全接口，支持多种协议和模型系列。

OpenAI 兼容 · Chat

POST/v1/chat/completions

该调用方式下无法统计工具调用；如需准确的工具调用计费，请使用下方 Responses 协议接入。

请求参数：model（模型标识）、messages（消息数组，含 role 与 content）、可选 stream / temperature / max_tokens 等 OpenAI 标准参数。

流式输出

curl -X POST https://model-router.edu-aliyun.com/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3.8-27b",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": true,
  "stream_options": {"include_usage": true}
}'

响应为 SSE 流（data: {...} 逐块返回，末帧含 usage 统计，以 data: [DONE] 结束）。

多模态输入（图 + 文）

curl -X POST https://model-router.edu-aliyun.com/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3.8-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "https://<替换为你自己的图片地址>"}},
        {"type": "text", "text": "这是什么"}
      ]
    }
  ]
}'

Responses 协议（推荐 Agent 场景）

POST/v1/responses

相较 OpenAI Chat Completions 的优势：

内置工具：联网搜索、网页抓取、代码解释器、文搜图、图搜图、知识库搜索等开箱即用
更灵活的输入：支持直接传字符串，也兼容 Chat 格式的消息数组
简化上下文管理：传 previous_response_id 即可续接对话，无需手动拼历史
便捷上下文缓存：请求头加 x-dashscope-session-cache: enable 自动缓存上下文，降低多轮延迟与成本

curl -X POST https://model-router.edu-aliyun.com/v1/responses \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3.8-27b",
  "input": "帮我查一下杭州明天的天气，再生成一张相关意境的图片",
  "tools": [
    {"type": "web_search"},
    {"type": "web_search_image"}
  ]
}'

Anthropic 兼容

POST/v1/messages

兼容 Anthropic Messages 格式，可直接使用 Claude SDK 接入；使用前请确认所选模型支持 Anthropic 协议。必填：model、max_tokens、messages；内容块支持 text / image / video / tool_use / tool_result。

curl -X POST https://model-router.edu-aliyun.com/v1/messages \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3.8-27b",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": [{"type": "text", "text": "你好，请介绍一下自己"}]}
  ]
}'

多模态对话（视觉理解）

POST/v1/chat/completions

与文本对话同接口，把 content 换成数组，图片以 image_url 传入（公网可访问 URL 或 data:image/...;base64）。

curl -X POST https://model-router.edu-aliyun.com/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3-vl-flash",
  "messages": [
    {"role": "user", "content": [
      {"type": "image_url", "image_url": {"url": "https://<你的图片地址>"}},
      {"type": "text", "text": "图里有什么？"}
    ]}
  ]
}'

图片按 image_tokens 计入输入 Token（示例：一张 1024×1024 图约 1024 tokens，数值以实际计量为准），计费与文本 Token 分档。

全模态对话

POST/v1/chat/completions

用 modalities 声明期望的输出形态：只要文字回 ["text"]；需要语音回复用 ["text","audio"]。输入侧可混排文本、音频、图片。

curl -X POST https://model-router.edu-aliyun.com/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3.5-omni-flash",
  "messages": [
    {"role": "user", "content": [{"type": "text", "text": "用一句话介绍武汉"}]}
  ],
  "modalities": ["text"]
}'

用量按模态分别回传：prompt_tokens_details / completion_tokens_details 内的 text_tokens、audio_tokens、image_tokens。音频输出档位建议先与云开智捷技术支持联调确认。

语音合成

POST/v1/audio/speech

语音合成接口，提供多种拟人音色，支持多语言及方言，并可在同一音色下输出多语言内容；系统自适应语气，流畅处理复杂文本。按字符计费。

curl -X POST https://model-router.edu-aliyun.com/v1/audio/speech \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3-tts-instruct-flash",
  "input": {
    "text": "那我来给大家推荐一款T恤，这款呢真的是超级好看。",
    "voice": "Cherry",
    "language_type": "Chinese"
  }
}'

响应中音频在 output.audio.url（同时给 output.audio.expires_at 过期时间戳），usage.characters 为计费用的合成字符数。请即时下载转存，不要直接长期引用该 URL；也支持流式返回音频分片。

语音理解

语音识别支持两种方式，按音频时长计费，支持多语种。

实时识别

POST/v1/chat/completions

对话式识别（如 qwen/qwen3-asr-flash-2026-02-10）：音频以 input_audio 内容块放入 messages（公网 URL 或 data:audio/...;base64 内联均可），识别文本在回复的 content 中返回，usage 为 Token 计数。

curl -X POST https://model-router.edu-aliyun.com/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3-asr-flash-2026-02-10",
  "messages": [
    {"role": "user", "content": [
      {"type": "input_audio", "input_audio": {"data": "https://<替换为你自己的音频地址>"}}
    ]}
  ]
}'

录音文件识别（异步）

POST/v1/audio/transcriptions

长音频批量转写（如 qwen/qwen3-asr-flash-filetrans）：须携带 X-DashScope-Async: enable 头，返回 task_id 后轮询。

# 录音文件识别：注意必须携带异步头
curl -X POST https://model-router.edu-aliyun.com/v1/audio/transcriptions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
  "model": "qwen/qwen3-asr-flash-filetrans",
  "input": {
    "file_url": "https://<替换为你自己的音频地址>"
  },
  "parameters": {
    "channel_id": [0],
    "enable_itn": false,
    "enable_words": true
  }
}'

响应返回 task_id 与 task_status，请使用异步任务查询接口轮询；任务完成后转写全文以 output.result.transcription_url JSON 文件链接形式给出（含有效期，请及时下载转存）。

图片生成

POST/v1/images/generations

文生图（同步）与图片编辑（单图编辑 / 多图融合）；千问系列另支持异步方式。按张计费。

curl -X POST https://model-router.edu-aliyun.com/v1/images/generations \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen-image-2.0-pro",
  "input": {
    "messages": [
      {"role": "user", "content": [{"text": "冬日北京的都市街景，水彩风格"}]}
    ]
  },
  "parameters": {
    "negative_prompt": "低分辨率，低画质，画面过饱和",
    "prompt_extend": true,
    "size": "1328*1328",
    "n": 1
  }
}'

同步调用直接返回图片 URL；异步调用（加 X-DashScope-Async: enable 头）返回 task_id，走任务查询取结果。

图片编辑

POST/v1/images/generations

与图片生成同接口，在 content 里同时给出原图与编辑指令；同样可能返回异步任务，用「异步任务查询」取结果。

curl -X POST https://model-router.edu-aliyun.com/v1/images/generations \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen-image-edit-plus",
  "input": {
    "messages": [
      {"role": "user", "content": [
        {"image": "https://<你的原图地址>"},
        {"text": "给猫加一顶红色帽子"}
      ]}
    ]
  },
  "parameters": {"n": 1}
}'

视频生成

POST/v1/videos/generations

支持文生视频、图生视频、参考图生视频三种类型，多模型可选。均为异步调用：先创建任务获取 task_id，再轮询结果；按分辨率 × 时长计费。

# 文生视频（注意异步头）
curl -X POST https://model-router.edu-aliyun.com/v1/videos/generations \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "X-MR-Async: true" \
  -d '{
  "model": "qwen/wan2.6-t2v",
  "input": {
    "prompt": "一只卡通小猫将军身穿金色盔甲，站在悬崖上眺望远方"
  },
  "parameters": {
    "size": "1280*720",
    "prompt_extend": true,
    "duration": 10,
    "shot_type": "multi"
  }
}'

图生视频

POST/v1/videos/generations

把首帧图片放进 input.img_url，必须携带异步头。

curl -X POST https://model-router.edu-aliyun.com/v1/videos/generations \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "X-MR-Async: true" \
  -d '{
  "model": "qwen/wan2.6-i2v-flash",
  "input": {"img_url": "https://<你的首帧图片地址>", "prompt": "镜头缓慢推进，猫眨眼"},
  "parameters": {"size": "480p", "duration": 5}
}'

尺寸写法因模型而异：图生视频接受档位串（如 480p），文生视频则要求 宽*高（如 1280*720），写错会直接报 size is not supported。产物 URL 带签名有效期，请及时转存。

向量

POST/v1/embeddings

支持文本向量（兼容 OpenAI Embeddings 格式）与多模态向量（文本/图片/视频输入，可选独立向量或融合向量）。

curl -X POST https://model-router.edu-aliyun.com/v1/embeddings \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/text-embedding-v4",
  "input": ["风急天高猿啸哀", "渚清沙白鸟飞回"],
  "dimensions": 1024,
  "encoding_format": "float"
}'

POST/v1/embeddings

多模态向量：入参是 input.contents 数组（不是字符串数组），文本与图片可混排。

curl -X POST https://model-router.edu-aliyun.com/v1/embeddings \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/tongyi-embedding-vision-plus",
  "input": {"contents": [{"text": "宇航员猫"}, {"image": "https://<你的图片地址>"}]}
}'

用量按模态拆分：input_tokens_details.image_tokens / text_tokens。

排序

POST/v1/rerank

重排序接口，支持纯文本排序（qwen3-rerank）与多模态排序（qwen3-vl-rerank），用于对候选文档按查询相关性重排。

curl -X POST https://model-router.edu-aliyun.com/v1/rerank \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3-vl-rerank",
  "input": {
    "query": {"text": "什么是文本排序模型"},
    "documents": [
      {"text": "文本排序模型广泛用于搜索引擎和推荐系统……"},
      {"image": "https://<替换为你自己的图片地址>"}
    ]
  },
  "parameters": {"return_documents": true, "top_n": 2}
}'

结果在 output.results[]（index 对应传入文档下标，relevance_score 为相关度）。query 支持两种写法：纯文本模型可直接给字符串，多模态模型给 {"text": "..."} 或 {"image": "..."}。

异步任务查询

GET/v1/tasks/{task_id}

查询异步任务（录音文件识别 / 异步图片 / 视频生成等）的状态与结果。状态流转：PENDING → RUNNING → SUCCEEDED / FAILED。

轮询要点（实测）：① 查询用的 task_id 取创建响应里的 output.task_id——自定义模型的标识带 {symbol}_ 前缀（如 custom_xxx），请勿误用顶层 id，否则报 invalid task_id format；② 状态值大小写因模型而异（部分返回小写 succeeded），请按大小写不敏感匹配终态；③ 任务刚创建后首次查询可能短暂返回 404（尚未可查），需容忍并重试，不要据此判失败。

curl -X GET https://model-router.edu-aliyun.com/v1/tasks/<task_id> \
  -H "Authorization: Bearer <YOUR_API_KEY>"

任务完成时，usage 含计费统计；结果位置随任务类型不同：图片/视频等媒体任务在 output 中直接给出结果 URL（视频为 output.video_url），录音文件转写在 output.result.transcription_url 给出 JSON 下载链接。结果链接均有有效期（任务查询响应里视频/音频另带 expires_at），请及时转存。建议轮询间隔 3~5 秒。

任务查询响应顶层为 output / usage / request_id / mr_req_id；output.task_status 到终态后，成功带结果字段，失败则带 output.code 与 output.message（例：InvalidParameter / size is not supported），请据此判定并停止轮询。

用量字段速查

以下为各接口返回的 usage 实测字段（2026-09-05 逐类目真实调用采集；字段随模型服务版本可能调整，统计口径以实际账单为准），做用量统计与成本核算时按此取值：

类目	usage 字段	结果位置
文本 / 多模态 / 全模态对话	`prompt_tokens`、`completion_tokens`、`total_tokens`；细分在 `prompt_tokens_details`（`text_tokens`、`image_tokens`、`audio_tokens`、`cached_tokens`）与 `completion_tokens_details`	`choices[0].message.content`
向量（文本）	`prompt_tokens`、`total_tokens`	`data[].embedding`
多模态向量	`input_tokens`、`output_tokens`、`total_tokens`；细分在 `input_tokens_details`（`image_tokens`、`text_tokens`）	`data[]`
重排序	`total_tokens`	`output.results[].relevance_score`
多模态重排序	`input_tokens`、`image_tokens`、`total_tokens`	`output.results[]`
语音合成	`characters`（合成字符数）	`output.audio.url`（带 `expires_at` 过期时间）
语音识别（实时）	`prompt_tokens`、`completion_tokens`、`total_tokens`	`choices[0].message.content`
图片生成	`image_count`、`size`、`input_tokens`、`output_tokens`	任务结果中的图片 URL
图片编辑	`image_count`、`width`、`height`	任务结果中的图片 URL
视频生成 / 图生视频	`video_count`、`duration`、`output_video_duration`、`input_video_duration`、`SR`（输出分辨率档）、`size`（部分模型）、`audio`（是否含音轨）	`output.video_url`

字段并非每个模型都全量返回（例如 size 只在部分视频模型出现）；建议按「有则取、无则回落总项」的方式解析，不要假设字段一定存在。

请求 ID 的三种形态

同一次调用在不同位置会出现三种 ID，彼此不能互相换算，排障与对账时请按用途选用：

形态	出现位置	用途
`chatcmpl-<uuid>`	OpenAI 兼容对话端点响应的 `id`	调用方本地关联请求与回复
`request_id`（uuid）	多数端点响应体（图片 / 视频 / 语音 / 排序 / 异步任务查询）	模型侧调用追踪
`mr_req_id`（形如 `R<32位hex>`）	网关透出的请求 ID（异步任务查询响应顶层、错误体；部分对话端点也返回）	与控制台「模型观测 / 账单明细」里的请求 ID 完全一致，排障与逐笔对账请优先记录它

若你的调用只拿到 chatcmpl-…，在控制台按它搜索是查不到的——请改用「调用时间 + 模型 + Key」组合定位，或联系云开智捷技术支持。

计费说明

文本对话 / 向量：按 Token 计费，单价按合同专属折扣结算，报价请联系云开智捷商务经理；命中缓存的输入按缓存价计
语音合成：按字符计费（usage.characters）；语音识别：文件转写按音频时长计费，实时识别接口返回的是 Token 计数，扣费口径以账单明细为准
图片：按张计费；视频：按分辨率 × 时长计费
思考模式（enable_thinking）：按思考单价计费，通常高于普通输入输出价
内置工具：联网搜索、代码解释器等可能产生额外费用，见 Responses 协议说明
合同折扣：控制台账单按你的合同折扣自动结算，无需换算
额度熔断：组织额度耗尽后调用被拒绝，请联系管理员或云开智捷商务增补

错误处理

HTTP	场景	建议处理
401	Key 无效或已删除	核对 Key 完整性；是否被管理员回收
403	该模型未对贵组织开通 / 额度不足	联系云开智捷商务增补模型范围或充值额度
429	触发限流	指数退避重试
5xx	模型服务暂时异常	稍后重试；持续异常联系云开智捷技术支持

排障流程（管理员侧）：

调用方优先记录响应中的 mr_req_id（形如 Rxxxxxxxx...，与平台账单/观测里的请求 ID 完全一致）；异步任务与部分端点还会返回 request_id。注意 OpenAI 兼容对话端点当前只返回 chatcmpl-…，它与网关请求 ID 不同源，无法直接换算
控制台「模型观测 → 调用记录」按请求 ID 搜索即可定位该笔调用的模型、Key、Token 与耗时，状态筛选可快速圈出失败调用；若手上只有 chatcmpl-…，请改用「调用时间 + 模型 + Key」组合定位
涉及扣费争议时，在「账单中心 → 账单明细」按同一请求 ID 搜索，点击该行查看计费构成（各计费段的用量、单价与费用）
失败调用的详细原因不在对客界面展示，请携带请求 ID 联系 whyk@whwispeed.com，云开智捷技术支持按请求逐笔核查

最佳实践

按用途发 Key：一个用途一把 Key（如「HR-周报机器人」），用量按 Key 归集到人，泄露时单点回收不影响其他业务
Agent 用 Responses：工具调用计量更完整、计费更准确
异步任务：轮询间隔 3~5 秒，注意保存 task_id；任务结果 URL 有过期时间，请及时转存
密钥安全：Key 只在服务端保存，绝不写入前端代码或仓库
超时与重试：长文本生成建议读超时 ≥120 秒；429/5xx 指数退避

密钥保管与轮换

API Key 等同于贵组织在本平台的身份凭证，持有即可调用并产生费用。平台不做设备或来源绑定，保管责任在调用方，请遵循以下规范：

只放服务端：Key 写入服务端环境变量或密钥管理系统，禁止出现在前端代码、移动端包、公开仓库与聊天记录中
一用途一 Key：控制台「成员与 Key」按用途命名发放；个人 Key 的消耗计入持有人月度预算，系统 Key 仅扣组织余额
明文只取一次：列表仅显示掩码；确需查看时通过「查看明文」获取，用完即关闭
定期轮换：建议每季度或人员变动时轮换——先新建 Key 并切换业务配置，验证通过后再删除旧 Key，避免调用中断
异常处置：发现疑似泄露立即在控制台删除该 Key（调用即刻失效），再到「账单中心」按该 Key 核对损失；历史用量仍保留可追溯
新 Key 生效：创建后鉴权存在数分钟传播延迟，若立即调用返回 401 请稍后重试，无需重建

获取支持

接入遇到问题？联系 whyk@whwispeed.com 或你的专属商务经理，本地化技术支持，响应时效以合同为准。企业客户可预约远程联调支持。