本文面向平台开发者,说明阿里百炼北京站渠道在 kapon 中暴露的 API 契约。开发者只需要使用 kapon Token 和模型名;百炼 API Key、DashScope BaseURL、渠道路由和成本对账由平台管理员维护。
本文描述的是 kapon 对外接口,不是阿里云控制台直连接口。默认服务地址示例为 https://models.kapon.cloud,请替换为你的平台实际域名。
读者范围
| 角色 | 需要关心 | 不需要关心 |
|---|
| 平台开发者 | kapon Token、模型名、对外路径、请求/响应格式、错误码和异步任务状态 | 阿里云控制台登录、百炼 API Key、DashScope 原生签名、渠道 base_url |
| 平台管理员 | 渠道 Key、模型权限、默认模型、价格、日志和消费对账 | 业务服务里的 SDK 代码 |
| 业务应用 | OpenAI SDK、Anthropic SDK 或 HTTP 请求 | 百炼账号区域、内部计费 SKU |
业务服务不要保存或透传阿里云百炼 API Key。平台开发者只使用 kapon Token;百炼 Key 仅配置在后台渠道中。
开发者接入路径
| 步骤 | Action | Expected |
|---|
| 1 | 从平台获取 kapon 模型调用 Token | 业务服务只保存 kapon Token,不保存百炼 API Key |
| 2 | 调用 GET $BASE_URL/v1/models | 能看到目标模型,例如 qwen3.7-plus、qwen3-vl-plus、wan2.7-t2v |
| 3 | 按 SDK 类型设置 base_url | OpenAI SDK 填 $BASE_URL/v1;Anthropic SDK 填 $BASE_URL |
| 4 | 先跑最小探针 | model list、非流式 chat、流式 chat、Responses、Anthropic Messages 至少各成功一次 |
| 5 | 保存请求 ID | 记录 X-Oneapi-Request-Id 或错误体 request_id,便于平台排查和对账 |
export BASE_URL="https://models.kapon.cloud"
export TOKEN="your-api-token"
所有接口统一使用 Bearer Token:
Authorization: Bearer $TOKEN
建议先调用模型列表确认当前 Token 可见模型:
curl "$BASE_URL/v1/models" \
-H "Authorization: Bearer $TOKEN"
Base URL 与 SDK
| 调用方式 | SDK base_url | 实际对外路径 | 说明 |
|---|
| OpenAI SDK 文本/视觉/Embedding/图像/视频 | https://models.kapon.cloud/v1 | /v1/... | 适合 chat.completions、responses、embeddings、images 以及支持自定义 HTTP 的视频任务 |
| Anthropic SDK | https://models.kapon.cloud | /v1/messages | Anthropic SDK 会拼接 /v1/messages,不要把 base URL 写成百炼 /apps/anthropic |
| curl / 原始 HTTP | https://models.kapon.cloud | 手动填写完整路径 | 示例均以 $BASE_URL/v1/... 展示 |
如果你在业务侧把 base_url 写成 https://dashscope.aliyuncs.com,请求会绕过 kapon,无法获得平台路由、统一计费、请求 ID、错误清洗和审计日志。
最小验收探针
| 能力 | 请求 | 通过标准 |
|---|
| 模型列表 | GET $BASE_URL/v1/models | 返回 200,响应中包含计划使用的模型 |
| Chat 非流式 | POST $BASE_URL/v1/chat/completions,stream=false 或不传 | 返回一条完整 assistant 消息和 usage |
| Chat 流式 | POST $BASE_URL/v1/chat/completions,stream=true | 返回 SSE chunk,最终包含结束事件或完整收敛状态 |
| Responses | POST $BASE_URL/v1/responses | 返回 OpenAI Responses 兼容对象;如启用缓存,usage 中保留缓存字段 |
| Anthropic Messages | POST $BASE_URL/v1/messages | 返回 Anthropic Messages 兼容对象,业务侧 SDK 不需要知道百炼 /apps/anthropic 路径 |
| 图像/视频 | POST $BASE_URL/v1/images/* 或 POST $BASE_URL/v1/videos | 图像按成功张数返回;视频创建后需要继续查询终态 |
接口矩阵
| 能力 | kapon 接口 | 百炼上游路径 | 说明 |
|---|
| 模型列表 | GET /v1/models | compatible-mode/v1/models | 返回当前 Token 与渠道配置可见模型 |
| Chat Completions | POST /v1/chat/completions | compatible-mode/v1/chat/completions 或 /api/v1/services/aigc/text-generation/generation / /api/v1/services/aigc/multimodal-generation/generation | 支持非流式、流式、文本和图像理解 |
| Responses | POST /v1/responses | compatible-mode/v1/responses | 支持 OpenAI Responses 非流式与流式 |
| Anthropic Messages | POST /v1/messages | /apps/anthropic/v1/messages | 支持 Anthropic Messages 非流式、流式和官方高级字段透传 |
| Embeddings | POST /v1/embeddings | /api/v1/services/embeddings/text-embedding/text-embedding;OpenAI API 模式为 compatible-mode/v1/embeddings | 文本向量 |
| 图像生成 | POST /v1/images/generations | /api/v1/services/aigc/multimodal-generation/generation | 文生图,按成功图片数计费 |
| 图像编辑 | POST /v1/images/edits | /api/v1/services/aigc/multimodal-generation/generation | 改图,建议传公网可访问 URL |
| 视频创建 | POST /v1/videos | /api/v1/services/aigc/video-generation/video-synthesis | 文生视频、图生视频、参考视频、视频编辑 |
| 视频查询 | GET /v1/videos/{video_id} | /api/v1/tasks/{task_id} | 查询异步任务状态与结果 URL |
| 视频下载 | GET /v1/videos/{video_id}/content | 结果 URL 代理下载 | 完成后下载视频文件 |
与百炼官方入口的关系
本文档中的 kapon 接口 是平台开发者使用的稳定契约;百炼上游路径 只用于解释后台渠道如何转发和排障。业务代码不要直接拼接百炼上游路径,也不要把百炼 API Key 放入业务服务。
| 官方百炼能力 | 百炼官方接入信息 | kapon 对外契约 |
|---|
| OpenAI Chat Completions | 北京兼容端点为 https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions | 使用 POST $BASE_URL/v1/chat/completions,SDK base_url 填 $BASE_URL/v1 |
| OpenAI Responses | 北京兼容端点为 https://dashscope.aliyuncs.com/compatible-mode/v1/responses | 使用 POST $BASE_URL/v1/responses |
| Anthropic Messages | 北京兼容端点为 https://dashscope.aliyuncs.com/apps/anthropic/v1/messages | 使用 POST $BASE_URL/v1/messages,SDK base_url 填 $BASE_URL |
| DashScope 原生文本 | POST /api/v1/services/aigc/text-generation/generation | 业务侧仍使用 OpenAI Chat Completions 形态,平台按模型和输入自动选择上游协议 |
| DashScope 原生多模态 | POST /api/v1/services/aigc/multimodal-generation/generation | 图像理解、图像生成和图像编辑由平台转换为百炼原生多模态请求 |
| DashScope 视频任务 | POST /api/v1/services/aigc/video-generation/video-synthesis + GET /api/v1/tasks/{task_id} | 使用 POST /v1/videos 创建任务,使用 GET /v1/videos/{video_id} 查询终态 |
百炼官方文档会按模型和地域更新参数。业务开发者优先遵循本页的 kapon 对外契约;需要确认某个模型的上游特性时,再参考百炼官方文档并通过平台验收。
官方文档核对
以下链接用于解释 kapon 后台为什么采用对应上游协议。平台开发者的业务代码仍以本页的 kapon 对外契约为准。
最后核查日期:2026-06-15。
平台开发者契约
| 项目 | 约定 |
|---|
| 服务地址 | 使用平台域名,例如 https://models.kapon.cloud;SDK base_url 通常填写到 /v1 |
| 认证 | 只使用 kapon Token;不要在业务服务中保存阿里云百炼 API Key |
| 模型名 | 请求体里的 model 使用平台公开模型名,例如 qwen3.7-plus、qwen3-vl-plus、wan2.7-t2v |
| 可见性 | 以 GET /v1/models 返回为准;模型可能因 Token 权限、渠道模型配置或百炼账号权益不可见 |
| 区域 | 当前文档只描述北京站渠道;不要把国际站 workspace endpoint 或 Key 混入北京站渠道 |
| 请求 ID | 平台会返回 X-Oneapi-Request-Id 和错误体里的 error.request_id,排查工单优先提供该 ID |
| 计费 | 文本/视觉/Embedding 按 token 计量;图片按成功图片张数;视频按成功输出秒数与分辨率档位 |
| 上游透传 | 百炼上游错误会保留可读语义,但平台会清理密钥、内部 URL 等敏感信息 |
Usage 与缓存计费字段
文本、视觉理解和 Embedding 响应会尽量保留 OpenAI 兼容 usage 字段。百炼缓存相关字段主要影响输入 token 的计费方式,开发者可以把它们用于成本解释和对账,不应自行按这些字段扣费。
| 字段 | 出现位置 | 含义 | 平台计费语义 |
|---|
prompt_tokens / input_tokens | OpenAI 兼容或 DashScope 原生 usage | 输入 token 总量 | 基础输入 token |
completion_tokens / output_tokens | OpenAI 兼容或 DashScope 原生 usage | 输出 token 总量 | 基础输出 token |
prompt_tokens_details.cached_tokens | OpenAI 兼容 usage | 命中缓存的输入 token | 按模型缓存命中比例折算,显式缓存命中通常低于隐式缓存 |
prompt_tokens_details.cache_creation_input_tokens | OpenAI 兼容 usage | 本次新创建显式缓存的 token | 按显式缓存写入比例折算,通常高于标准输入价 |
usage.cache_read_input_tokens | Anthropic Messages usage | Anthropic 兼容入口命中缓存的 token | 按百炼 Anthropic 缓存命中规则折算 |
usage.cache_creation_input_tokens | Anthropic Messages usage | Anthropic 兼容入口创建缓存的 token | 按显式缓存写入比例折算 |
缓存字段是上游返回的用量信号。最终消费以平台日志和账单为准;如果响应 usage 与消费记录不一致,请带上 X-Oneapi-Request-Id 或错误体中的 request_id 排查。
协议兼容边界
| 协议 | 当前支持 | 需要单独验收 |
|---|
| OpenAI Chat Completions | 文本、流式、图像理解输入、基础 usage | 模型专属工具调用细节、超长上下文、特殊采样参数 |
| OpenAI Responses | 非流式、流式、文本 input 形态 | 复杂工具、文件输入、Responses 高级内置工具 |
| Anthropic Messages | 非流式、流式、anthropic-version / anthropic-beta header 透传、thinking、tool、图片/视频理解、cache_control 字段透传和 Anthropic usage 缓存字段映射 | 复杂 tool 结果、多轮 thinking、媒体输入与缓存组合的真实上游抽样 |
| DashScope 原生文本/多模态 | 由渠道内部转换,开发者仍使用 OpenAI 形态 | 直接发送 DashScope 原生请求体 |
| 图像 | 文生图、改图、URL 或 base64 结果转换 | 本地文件直传、不可公网访问图片 URL |
| 视频 | 创建、查询、下载、参考图片/视频映射 | 上游未开通模型、过期结果 URL 续期 |
本页描述的是 kapon 对外 API 契约。不要把 DashScope 原生请求体直接发送到 kapon,除非对应字段已经在本文或通用 OpenAI/Claude 文档中声明。
SDK 接入
OpenAI SDK
from openai import OpenAI
client = OpenAI(
api_key="your-api-token",
base_url="https://models.kapon.cloud/v1",
)
resp = client.chat.completions.create(
model="qwen3.7-plus",
messages=[{"role": "user", "content": "用一句话说明百炼接入方式。"}],
)
print(resp.choices[0].message.content)
Responses、Embeddings、Images 和 Videos 入口也使用同一个 base_url 与 Token。不同 SDK 对非官方视频扩展字段的支持不完全一致;如果 SDK 类型不接受扩展字段,可以改用原始 HTTP 请求。
Anthropic SDK
import anthropic
client = anthropic.Anthropic(
api_key="your-api-token",
base_url="https://models.kapon.cloud",
)
message = client.messages.create(
model="qwen3.7-plus",
max_tokens=1024,
messages=[{"role": "user", "content": "用 Anthropic Messages 格式回复一句话。"}],
)
print(message.content[0].text)
百炼 Anthropic 入口会透传 anthropic-version、anthropic-beta、thinking、tool、媒体输入和 cache_control 等 Messages 字段,并保留上游返回的缓存 usage 字段。复杂 tool 结果、多轮 thinking、媒体输入与缓存组合仍建议按模型做真实上游抽样。
Chat Completions
非流式
curl -X POST "$BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.7-plus",
"messages": [
{"role": "system", "content": "你是一个简洁的中文助手。"},
{"role": "user", "content": "给我三个 API 接入验收点。"}
]
}'
curl -N -X POST "$BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.7-plus",
"stream": true,
"messages": [
{"role": "user", "content": "用 30 字说明统一网关的价值。"}
]
}'
图像理解
curl -X POST "$BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-vl-plus",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "描述这张图片的主体和风格。"},
{"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]
}
]
}'
Responses
curl -X POST "$BASE_URL/v1/responses" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.7-plus",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "把这段需求整理成验收标准。"}
]
}
]
}'
流式调用时加入 "stream": true。
Anthropic Messages
curl -X POST "$BASE_URL/v1/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.7-plus",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "用 Anthropic Messages 格式返回一句问候。"}
]
}'
该入口透传 Anthropic Messages 字段,但最终可用性仍取决于百炼账号权限和具体模型。涉及 thinking、tool、媒体输入与缓存组合时,请保留请求 ID 并按模型抽样验收。
Embeddings
curl -X POST "$BASE_URL/v1/embeddings" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-v4",
"input": ["阿里百炼模型接入", "统一网关与计费"]
}'
图像生成
curl -X POST "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-2.0-pro",
"prompt": "干净的 SaaS 控制台产品宣传图,真实屏幕,浅色背景",
"size": "1024x1024",
"response_format": "url",
"n": 1
}'
百炼图像结果支持 url 与 b64_json。当请求 b64_json 但上游只返回 URL 时,平台会尝试下载结果并转成 base64。
图像编辑
curl -X POST "$BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-edit-plus",
"prompt": "保持主体不变,替换为干净的电商白底图",
"images": [
{"image_url": "https://example.com/product.png"}
],
"size": "1024x1024",
"response_format": "url",
"n": 1
}'
视频生成
百炼视频为异步任务。创建任务返回 video_id 后,需要查询任务状态,完成后再下载文件。
文生视频
curl -X POST "$BASE_URL/v1/videos" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-t2v",
"prompt": "城市夜景中的新能源车广告片,电影感镜头,平稳推进",
"seconds": 5,
"resolution": "720p"
}'
图生视频
curl -X POST "$BASE_URL/v1/videos" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-i2v",
"prompt": "让画面中的人物自然转身微笑,镜头轻微推进",
"input_reference": {"image_url": "https://example.com/first-frame.jpg"},
"seconds": 5,
"resolution": "720p"
}'
参考视频生成
curl -X POST "$BASE_URL/v1/videos" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-r2v",
"prompt": "参考视频运动节奏,生成同风格产品展示短片",
"references": {
"video": ["https://example.com/reference.mp4"]
},
"input_reference": {"image_url": "https://example.com/product.png"},
"seconds": 5,
"resolution": "720p"
}'
查询与下载
curl "$BASE_URL/v1/videos/$VIDEO_ID" \
-H "Authorization: Bearer $TOKEN"
任务成功后通常返回 completed,结果 URL 会带 expires_at 过期信号。客户端也建议兼容本地异步任务口径中的 success。
curl -L "$BASE_URL/v1/videos/$VIDEO_ID/content" \
-H "Authorization: Bearer $TOKEN" \
--output "$VIDEO_ID.mp4"
异步任务状态
| 平台状态 | 含义 | 客户端建议 |
|---|
queued / in_progress / processing | 任务已创建或正在执行 | 继续轮询,建议指数退避 |
completed / success | 任务成功,通常包含结果 URL | 可以调用下载接口或读取结果 URL |
failed | 上游任务失败 | 记录 video_id、request_id 和错误信息后排查 |
cancelled | 任务取消或上游未继续执行 | 视业务需要重新创建任务 |
视频任务创建阶段只代表上游接受任务,不代表最终成功。对账和扣费应以终态成功结果为准。
视频参考输入规则
| 模型类型 | 推荐字段 | 平台映射到百炼 |
|---|
happyhorse-1.0-i2v | input_reference 或 input_image | 原生 img_url |
happyhorse-1.0-r2v | input_reference 图片 URL;公开 JSON 示例优先使用 {"image_url": "..."} 对象 | input.media[].type=reference_image |
wan2.7-i2v | input_reference 图片或视频 URL | 第一项视频映射为 first_clip,图片映射为 first_frame,后续图片映射为 last_frame |
wan2.7-r2v | references.video[] + 可选 input_reference 图片对象 | 视频映射为 reference_video,图片映射为 reference_image |
happyhorse-1.0-video-edit | 图片 input_reference 或 references.video[] | 图片输入兼容 img_url;references.video[] 映射为 reference_video |
wan2.7-videoedit | references.video[] + 可选图片 input_reference 对象 | 源视频映射为 video,图片映射为 reference_image |
参考素材 URL 需要能被百炼上游访问。视频 URL 建议使用 .mp4 或 .mov 后缀;图片 URL 建议使用公开 HTTPS 地址。
失败与排查
| 现象 | 建议处理 |
|---|
model_not_found 或模型不可见 | 先调用 GET /v1/models,确认 Token 权限、渠道模型配置和百炼账号权益 |
| 百炼上游返回权限错误 | 联系平台管理员检查百炼模型开通、API Key 权限和账号额度 |
| 图像编辑无产物 | 确认 images[].image_url 可公网访问,并且模型属于图像编辑分类 |
视频创建返回 invalid_duration | 百炼视频当前支持 2-15 秒;HappyHorse 系列最短 3 秒 |
视频创建返回 invalid_resolution | 百炼视频当前只接受 720p 或 1080p |
| 视频下载返回未就绪 | 先查询任务状态,等待 completed 后再下载 |
错误响应遵循平台统一格式,常见字段如下:
{
"error": {
"message": "model not found (request id: 20260615120000abcdef)",
"type": "invalid_request_error",
"code": "model_not_found",
"request_id": "20260615120000abcdef",
"upstream_request_id": "dashscope-request-id"
}
}
更多错误格式、请求 ID 和对账说明请参考 错误处理、请求 ID 与 账单对账。