Skip to main content
本文面向平台开发者,说明阿里百炼北京站渠道在 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 仅配置在后台渠道中。

开发者接入路径

步骤ActionExpected
1从平台获取 kapon 模型调用 Token业务服务只保存 kapon Token,不保存百炼 API Key
2调用 GET $BASE_URL/v1/models能看到目标模型,例如 qwen3.7-plusqwen3-vl-pluswan2.7-t2v
3按 SDK 类型设置 base_urlOpenAI 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.completionsresponsesembeddingsimages 以及支持自定义 HTTP 的视频任务
Anthropic SDKhttps://models.kapon.cloud/v1/messagesAnthropic SDK 会拼接 /v1/messages,不要把 base URL 写成百炼 /apps/anthropic
curl / 原始 HTTPhttps://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/completionsstream=false 或不传返回一条完整 assistant 消息和 usage
Chat 流式POST $BASE_URL/v1/chat/completionsstream=true返回 SSE chunk,最终包含结束事件或完整收敛状态
ResponsesPOST $BASE_URL/v1/responses返回 OpenAI Responses 兼容对象;如启用缓存,usage 中保留缓存字段
Anthropic MessagesPOST $BASE_URL/v1/messages返回 Anthropic Messages 兼容对象,业务侧 SDK 不需要知道百炼 /apps/anthropic 路径
图像/视频POST $BASE_URL/v1/images/*POST $BASE_URL/v1/videos图像按成功张数返回;视频创建后需要继续查询终态

接口矩阵

能力kapon 接口百炼上游路径说明
模型列表GET /v1/modelscompatible-mode/v1/models返回当前 Token 与渠道配置可见模型
Chat CompletionsPOST /v1/chat/completionscompatible-mode/v1/chat/completions/api/v1/services/aigc/text-generation/generation / /api/v1/services/aigc/multimodal-generation/generation支持非流式、流式、文本和图像理解
ResponsesPOST /v1/responsescompatible-mode/v1/responses支持 OpenAI Responses 非流式与流式
Anthropic MessagesPOST /v1/messages/apps/anthropic/v1/messages支持 Anthropic Messages 非流式、流式和官方高级字段透传
EmbeddingsPOST /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 对外契约为准。
主题官方文档
OpenAI Chat CompletionsOpenAI 兼容 Chat
OpenAI Responses创建响应
Anthropic MessagesAnthropic 兼容 Messages
DashScope 文本与多模态DashScope API 参考
万相 2.7 文生视频万相 2.7 文生视频 API 参考
万相 2.7 图生视频万相 2.7 图生视频 API 参考
上下文缓存上下文缓存 Context Cache
显式缓存实践百炼显式缓存最佳实践
最后核查日期:2026-06-15。

平台开发者契约

项目约定
服务地址使用平台域名,例如 https://models.kapon.cloud;SDK base_url 通常填写到 /v1
认证只使用 kapon Token;不要在业务服务中保存阿里云百炼 API Key
模型名请求体里的 model 使用平台公开模型名,例如 qwen3.7-plusqwen3-vl-pluswan2.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_tokensOpenAI 兼容或 DashScope 原生 usage输入 token 总量基础输入 token
completion_tokens / output_tokensOpenAI 兼容或 DashScope 原生 usage输出 token 总量基础输出 token
prompt_tokens_details.cached_tokensOpenAI 兼容 usage命中缓存的输入 token按模型缓存命中比例折算,显式缓存命中通常低于隐式缓存
prompt_tokens_details.cache_creation_input_tokensOpenAI 兼容 usage本次新创建显式缓存的 token按显式缓存写入比例折算,通常高于标准输入价
usage.cache_read_input_tokensAnthropic Messages usageAnthropic 兼容入口命中缓存的 token按百炼 Anthropic 缓存命中规则折算
usage.cache_creation_input_tokensAnthropic Messages usageAnthropic 兼容入口创建缓存的 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-versionanthropic-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
  }'
百炼图像结果支持 urlb64_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_idrequest_id 和错误信息后排查
cancelled任务取消或上游未继续执行视业务需要重新创建任务
视频任务创建阶段只代表上游接受任务,不代表最终成功。对账和扣费应以终态成功结果为准。

视频参考输入规则

模型类型推荐字段平台映射到百炼
happyhorse-1.0-i2vinput_referenceinput_image原生 img_url
happyhorse-1.0-r2vinput_reference 图片 URL;公开 JSON 示例优先使用 {"image_url": "..."} 对象input.media[].type=reference_image
wan2.7-i2vinput_reference 图片或视频 URL第一项视频映射为 first_clip,图片映射为 first_frame,后续图片映射为 last_frame
wan2.7-r2vreferences.video[] + 可选 input_reference 图片对象视频映射为 reference_video,图片映射为 reference_image
happyhorse-1.0-video-edit图片 input_referencereferences.video[]图片输入兼容 img_urlreferences.video[] 映射为 reference_video
wan2.7-videoeditreferences.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百炼视频当前只接受 720p1080p
视频下载返回未就绪先查询任务状态,等待 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账单对账