Ming2API Docs

文档中心

本页提供 Ming2API 接入、调用、鉴权、错误处理与运维配置说明，结构对标主流 API 文档体验，便于团队快速上手。

提示：接口遵循 OpenAI 兼容格式，你可以在现有 SDK 基础上最小改造接入。

产品概览

Ming2API 统一聚合多家大模型供应商，通过同一套网关协议管理模型调用、权限控制、日志审计和账单统计。

兼容常见 OpenAI Chat/Embeddings 调用方式
支持按模型可用性、成本和延迟进行智能路由
支持团队 Token、配额、限流和安全审计

3 分钟接入

1）创建 API Token；2）设置 Base URL；3）按标准 OpenAI 格式发起请求。

API 基础地址：https://api.example.com

WorkBuddy 配置指导

WorkBuddy 支持通过自定义模型接入 Ming2API，无需手动编辑配置文件，全程图形化操作。

配置步骤

创建 API Token：在令牌管理页面创建新的 API Token，复制保存备用。
打开模型设置：在 WorkBuddy 中进入「设置」→「模型」页面。
添加自定义模型：点击「添加模型」按钮，选择「自定义API」或「Custom」选项。
填写配置信息：

配置参数：

提供商：选择「自定义API」或「Custom」
API 地址（Base URL）：https://api.example.com/v1
API Key：填入第 1 步创建的 Token
模型名称：输入你要使用的模型标识，如 gpt-4o-mini、qwen-plus 等。查看可用模型

高级配置（可选）

配置项	说明
自定义协议	如果模型服务使用非标准 URL 路径（如经过网关或代理层封装），可开启此选项。开启后直接使用填写的 URL 发起请求，跳过路径校验与自动补全逻辑。
能力标记	选择标准供应商时，工具调用、图片输入、推理模式等能力标记会自动写入，无需手动配置。

使用示例

配置完成后，在对话界面的模型选择器中即可看到自定义模型分组，选择后即可开始使用。

# 验证配置是否成功 curl -X POST "https://api.example.com/v1/chat/completions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [ {"role":"user","content":"Hello, WorkBuddy!"} ] }'

TIP：已通过 ~/.codebuddy/models.json 配置的自定义模型在界面升级后仍可正常使用，并可通过 UI 界面查看、编辑或删除，无需再直接操作配置文件。

鉴权方式

所有请求都需要在 Header 中传入 Authorization: Bearer <API_KEY>。建议你为不同业务创建独立 Token，以便审计与限流。

安全建议：生产环境请通过服务端中转调用，不要把长期 Token 暴露在前端代码中。

Chat Completions

核心对话接口，支持同步/流式输出、Tool Calls（函数调用）、Thinking 模式、千问批量推理等高级能力。

POST /v1/chat/completions 对话补全 · 支持流式 ▼

请求头

Header	Authorization 必填 Bearer YOUR_API_KEY
Content-Type	Content-Type application/json

请求体参数

参数	类型	必填	说明
model	string	是	模型标识符，如 `gpt-4o-mini`、`moonshot-v1-8k`、`qwen-plus` 等。
messages	array	是	消息数组，每条消息包含 `role`（system/user/assistant/tool）和 `content`。
stream	boolean	否	是否开启流式输出（SSE），默认 `false`。开启后响应头为 `text/event-stream`。
temperature	number	否	采样温度，0~2 之间，默认约 0.7。值越高输出越随机。
max_tokens	integer	否	最大输出 token 数，默认根据模型上下文窗口自动计算。
tools	array	否	工具定义数组，用于 Tool Calls（函数调用）。每项包含 `type` 和 `function`。
tool_choice	string/object	否	控制工具调用策略。可选 `auto`、`none` 或指定函数对象。千问部分模型不支持 Tool Call。
enable_thinking	boolean	否	是否启用 Thinking（推理）模式。支持该模式的模型会在输出中包含 `reasoning_content`。需要模型后台配置支持。
thinking_budget	integer	否	Thinking 模式的 token 预算上限。设置后自动启用 Thinking。最大不超过模型支持上限。
response_format	object	否	限制输出格式，如 `{"type":"json_object"}` 强制 JSON 输出。
top_p	number	否	核采样阈值，与 temperature 二选一。
frequency_penalty	number	否	频率惩罚系数，-2.0 ~ 2.0。
presence_penalty	number	否	存在惩罚系数，-2.0 ~ 2.0。
stop	string/array	否	生成停止词，达到后终止输出。可传字符串或字符串数组。

消息结构示例

"messages": [ {"role": "system", "content": "你是一个专业助手"}, {"role": "user", "content": "解释量子计算的基本原理"}, {"role": "assistant", "content": "...", "tool_calls": [...]}, {"role": "tool", "tool_call_id": "xxx", "content": "..."} ]

Tool Call 示例

// 请求 { "model": "gpt-4o-mini", "messages": [{"role":"user","content":"北京今天天气怎么样？"}], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "获取指定城市天气", "parameters": { "type": "object", "properties": { "city": {"type":"string","description":"城市名"} }, "required": ["city"] } } } ], "tool_choice": "auto" }

流式响应（SSE）

curl -X POST "https://api.example.com/v1/chat/completions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role":"user","content":"写一首诗"}], "stream": true }' # 响应为 SSE 格式： data: {"id":"ai_xxx","object":"chat.completion.chunk","created":1234567890,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]} data: {"id":"ai_xxx","object":"chat.completion.chunk","created":1234567890,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"眠"},"finish_reason":null}]} ... event: complete data: {"type":"stream_complete","chunks":15,"content_length":45} data: [DONE]

响应状态码

200 成功 400 参数错误 401 鉴权失败 402 余额不足 403 无权访问该模型 404 模型不存在 429 请求限流 500 服务器内部错误

成功响应示例（非流式）

{ "id": "ai_abc123def456", "object": "chat.completion", "created": 1234567890, "model": "gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "北京今天天气晴朗，温度15-25°C，适宜出行。" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 28, "completion_tokens": 42, "total_tokens": 70, "cached_tokens": 0 } }

图像生成

基于文本描述生成图像，支持通义万相等图像生成模型。图像生成为异步任务，后端会自动轮询直到图片生成完成。

POST /v1/images/generations 图像生成 ▼

请求头

Header	Authorization 必填 Bearer YOUR_API_KEY
Content-Type	Content-Type application/json

请求体参数

参数	类型	必填	说明
model	string	否	模型名称，默认为 `wanx-v1`（通义万相）。
prompt	string	是	图像描述文本，描述越详细生成效果越好。
size	string	否	图像尺寸，支持 `1024x1024`、`512x512`、`768x768`。DashScope API 会自动转换为 `1024*1024` 格式。
async	boolean	否	是否异步返回。默认为 `false`（同步等待结果）。设为 `true` 时立即返回 task_id，前端需轮询 `/v1/tasks` 接口获取结果。

请求示例

curl -X POST "https://api.example.com/v1/images/generations" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "wanx-v1", "prompt": "一只可爱的猫咪在草地上玩耍，阳光明媚", "n": 1, "size": "1024x1024", "async": false }'

响应状态码

200 成功 400 参数错误 401 鉴权失败 402 余额不足 404 模型不存在 500 服务器内部错误

成功响应示例

{ "created": 1234567890, "data": [ { "url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/7d/aa/20260508/cfc32567/556c0d1a-1e2b-4aef-b418-462320cd7cad359643836.png?Expires=1778829207&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=OtFr0RoN3f0ro4Bo31a%2F5qWR6Ks%3D" } ] }

注意

图像生成为异步任务，后端会自动轮询等待生成完成（最长 60 秒）
返回的 URL 为阿里云 OSS 地址，有效期约 24 小时，建议及时下载保存
数据库模型需将 model_type 设置为 image 才能调用此接口

视频生成

基于文本描述或参考图片生成视频，支持通义万相视频生成模型。视频生成为异步任务，会返回 task_id 供后续查询状态。

POST /v1/videos/generations 视频生成 ▼

请求头

Header	Authorization 必填 Bearer YOUR_API_KEY
Content-Type	Content-Type application/json

请求体参数

参数	类型	必填	说明
model	string	否	模型名称，默认为 `wanx-video`。
prompt	string	是	视频描述文本，描述越详细生成效果越好。
negative_prompt	string	否	负面提示词，描述不希望出现的元素。
image_urls	array[string]	否	参考图片 URL，图生视频时使用。
video_url	string	否	参考视频 URL，视频续写时使用。
resolution	string	否	生成视频的分辨率。当 model 是 Kling，可选值为 720P、1080P，默认为 720P；当 model 是 Hailuo，可选值为 768P、1080P，默认为 768P；当 model 是 Vidu，可选值为 720P、1080P，默认为 720P；当 model 是 GV，可选值为 720P、1080P，默认为 720P；当 model 是 OS，可选值为 720P；当 model 是 PixVerse，可选值为 540p、720p、1080p、2k、4k，默认为 720p。
aspect_ratio	string	否	指定所生成视频的宽高比。当 model 是 Kling，当文生视频时，则可选值为 16:9、9:16、1:1，默认为 16:9；当 model 是 Vidu，当文生视频时和使用参考图片生成时，则可选值为 16:9、9:16、4:3、3:4、1:1，其中仅版本 q2 支持 4:3、3:4；当 model 是 GV，则可选值为 16:9、9:16，默认为 16:9；当 model 是 OS，当文生视频时，则可选值为 16:9、9:16，默认为 16:9；当 model 是 Hailuo，则暂不支持；当 model 是 PixVerse，则可选值为 16:9、4:3、1:1、3:4、9:16、2:3、3:2、21:9。
duration	integer	否	生成视频的时长，单位：秒。当 model 是 Kling，可选值为 5、10，默认为 5；当 model 是 Hailuo，可选值为 6、10，默认为 6；当 model 是 Vidu，可指定 1-10；当 model 是 GV，可选值为 8，默认为 8；当 model 是 OS，可选值为 4、8、12，默认为 8；当 model 是 PixVerse，可指定 1-15，默认为 5。

请求示例

curl -X POST "https://api.example.com/v1/videos/generations" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "wanx-video", "prompt": "海浪拍打沙滩，夕阳下的美景", "negative_prompt": "模糊、抖动", "resolution": "720P", "aspect_ratio": "16:9", "duration": 5 }'

响应状态码

200 成功 400 参数错误 401 鉴权失败 402 余额不足 404 模型不存在 500 服务器内部错误

成功响应示例

{ "task_id": "task_abc123def456", "video_url": null, "status": "PROCESSING", "created": 1234567890 }

任务状态查询

视频生成为异步任务，需要轮询查询任务状态获取最终视频 URL：

curl -X GET "https://dashscope.aliyuncs.com/api/v1/tasks/YOUR_TASK_ID" \ -H "Authorization: Bearer YOUR_DASHSCOPE_API_KEY"

任务状态响应

// 处理中 { "output": { "task_status": "PROCESSING" } } // 成功 { "output": { "task_status": "SUCCEEDED", "video_url": "https://xxx.mp4" } } // 失败 { "output": { "task_status": "FAILED", "message": "错误信息" } }

注意

视频生成为异步任务，立即返回 task_id
需要客户端自行轮询查询任务状态获取最终视频 URL
数据库模型需将 model_type 设置为 video 才能调用此接口
视频生成通常需要 1-3 分钟，请合理设计轮询间隔

任务查询

查询图像或视频生成任务的状态。对于异步任务，可以使用返回的 task_id 查询最终结果。

GET /v1/tasks 查询任务状态 ▼

请求头

Header	Authorization 必填 Bearer YOUR_API_KEY

请求参数

参数	类型	必填	说明
task_id	string	是	任务 ID，从图像/视频生成接口返回的 task_id。
model	string	是	模型名称，参考模型列表。

请求示例

curl -X GET "https://api.example.com/v1/tasks?task_id=task_abc123def456" \ -H "Authorization: Bearer YOUR_API_KEY"

响应状态码

200 成功 400 参数错误 401 鉴权失败 404 任务不存在 500 服务器内部错误

成功响应示例（处理中）

{ "task_id": "task_abc123def456", "status": "PROCESSING", "created": 1234567890 }

成功响应示例（图像生成完成）

{ "task_id": "task_abc123def456", "status": "SUCCEEDED", "created": 1234567890, "image_url": "https://dashscope-result-xxx.oss-cn-shanghai.aliyuncs.com/xxx.png" }

成功响应示例（视频生成完成）

{ "task_id": "task_abc123def456", "status": "SUCCEEDED", "created": 1234567890, "video_url": "https://dashscope-result-xxx.oss-cn-shanghai.aliyuncs.com/xxx.mp4" }

失败响应示例

{ "task_id": "task_abc123def456", "status": "FAILED", "created": 1234567890, "message": "错误信息描述" }

注意

图像生成任务会在后端自动轮询，前端无需查询可直接获取结果
视频生成任务需要前端轮询此接口获取最终视频 URL
建议轮询间隔：初始 2 秒，后续每次间隔递增（2s, 4s, 8s...），最长不超过 30 秒
任务状态：PROCESSING（处理中）、SUCCEEDED（成功）、FAILED（失败）

模型列表

查询当前 API Key 有权访问的所有可用模型列表，包括模型 ID、上下文长度、所属供应商等元信息。

GET /v1/models 获取可用模型列表 ▼

请求头

Header	Authorization 必填 Bearer YOUR_API_KEY

请求参数

该接口无需 URL 参数，仅通过 Header 鉴权即可返回当前 Token 有权限访问的模型列表。

响应字段

字段	类型	说明
object	string	固定值 `"list"`
data	array	模型对象数组，每项包含 id、object、created、owned_by 等字段

请求示例

curl -X GET "https://api.example.com/v1/models" \ -H "Authorization: Bearer YOUR_API_KEY"

响应状态码

200 成功 401 鉴权失败

成功响应示例

{ "object": "list", "data": [ { "id": "gpt-4o-mini", "object": "model", "created": 1717608, "owned_by": "openai" }, { "id": "moonshot-v1-8k", "object": "model", "created": 1717608, "owned_by": "moonshot" }, { "id": "qwen-plus", "object": "model", "created": 1717608, "owned_by": "qwen" } ] }

Responses API

OpenAI Responses API 格式接口，与 Chat Completions 功能一致但响应格式不同。采用 input 数组替代 messages，更适合多轮对话和复杂任务。

POST /v1/responses Responses 格式对话 ▼

请求头

Header	Authorization 必填 Bearer YOUR_API_KEY
Content-Type	Content-Type application/json

请求体参数

参数	类型	必填	说明
model	string	是	模型标识符，同 Chat Completions。
input	array	是	用户输入数组，每项可为字符串或包含 `role` 和 `content` 的对象。
stream	boolean	否	是否开启流式输出，默认 `false`。
stream_options	object	否	流式选项，如 `{"include_usage": true}` 在最后包含 usage 信息。
tools	array	否	工具定义数组，用于函数调用。
tool_choice	string/object	否	工具调用策略，同 Chat Completions。
temperature	number	否	采样温度。
max_output_tokens	integer	否	最大输出 token 数（Responses API 参数名）。
enable_thinking	boolean	否	是否启用 Thinking 模式。
thinking_budget	integer	否	Thinking token 预算上限。
response_format	object	否	限制输出格式，如 JSON。
user	string	否	终端用户标识，用于风控和审计。

请求示例

流式响应（SSE）

curl -X POST "https://api.example.com/v1/responses" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "input": [{"role":"user","content":"写一个冒泡排序"}], "stream": true, "stream_options": {"include_usage": true} }' # 响应为 SSE 格式，带 Responses API 格式转换： data: {"id":"resp_xxx","type":"response.done","status":{"completed":false}} data: {"id":"resp_xxx","type":"response.output_item.done","output_index":0,"content":[{"type":"function_call","id":"fc_xxx","name":"get_weather","arguments":"{\"city\":\"Beijing\"}"}]} event: complete data: {"type":"response.done","response":{"id":"resp_xxx","status":{"completed":true}},"usage":{"prompt_tokens":20,"completion_tokens":35,"total_tokens":55}} data: [DONE]

响应状态码

200 成功 400 参数错误 401 鉴权失败 402 余额不足 403 无权访问该模型 404 模型不存在 429 请求限流 500 服务器内部错误

成功响应示例

{ "id": "resp_abc123", "object": "response", "status": "completed", "model": "gpt-4o-mini", "output": [ { "id": "out_xxx", "type": "message", "content": [ { "type": "output_text", "text": "机器学习是人工智能的一个分支，它使计算机能够从数据中学习并改进性能。" } ] } ], "usage": { "input_tokens": 25, "output_tokens": 68, "total_tokens": 93 } }

错误码

错误码已按"错误码 + HTTP 状态 + 说明 + 排查建议"整理，方便你快速定位问题。

错误码	HTTP 状态	说明	排查建议
INVALID_REQUEST	400	请求参数缺失或格式错误（常见为缺少 model 或 messages）。	检查请求体字段完整性与 JSON 格式。
MISSING_REQUIRED_PARAMETER	400	messages 为空。	messages 数组至少需要一条消息。
UNAUTHORIZED	401	缺少 Authorization Header。	请求头中必须包含 Authorization: Bearer xxx。
INVALID_API_KEY	401	API Key 无效、过期或被禁用。	确认 Authorization 头中 Key 的有效性。
INSUFFICIENT_QUOTA	402	账户余额不足或已耗尽。	充值额度或检查套餐有效期。
MODEL_NOT_ALLOWED	403	当前 API Key 未授权访问该模型。	在控制台检查 Key 权限范围和模型绑定。
MODEL_NOT_FOUND	404	指定模型不存在、不可用或未配置渠道。	核对模型 ID、渠道配置与可用状态。
RATE_LIMIT_EXCEEDED	429	请求频率超出限制。	降低请求频率或升级限流配额。
STREAM_ERROR	500	流式响应处理异常。	检查网络连接，上游供应商状态。
VENDOR_ERROR	502	上游供应商 API 调用失败（余额不足、限流等）。	查看上游返回详情，配置重试和降级策略。
NO_CHANNEL_AVAILABLE	503	无可用渠道，或所有渠道均处于不可用状态。	检查渠道健康状态并启用备用渠道。

限流与配额

可在控制台按应用、Token、团队设置 QPS、并发上限和日调用配额，超限策略支持阻断或排队。

回调与告警

支持对请求失败率、延迟飙升、余额不足等事件进行 Webhook 回调，便于与企业告警系统集成。

更多内容可继续扩展：SDK 示例、迁移指南、最佳实践、SLA 说明、私有化部署文档。