Vega VL HOT
- Endpoint:
https://mmu.vod-qcloud.com/v1/chat/completions - 认证: VOD AIGC API Token(
Authorization: Bearer或x-api-key) - 协议: OpenAI Chat Completions 兼容,可直接使用 OpenAI SDK
Vega-VL 是 WAND 的多模态理解模型(VL = Vision-Language),可分析文本、图片、音频、文件(PDF 等)、视频,并以文本或 JSON 返回结果。常见用法:视频摘要、章节切分、精彩片段提取、画面文字识别、图片打标签、录音内容提取、文档问答。
本文按接入顺序组织:
| 章节 | 回答的问题 |
|---|---|
| 1. 调用步骤 | 从开通到跑通第一次调用要做什么 |
| 2. 版本差异 | Lite / Flash / Pro 怎么选 |
| 3. 关键入参与出参 | 请求怎么写、响应怎么读,各版本有什么不同 |
| 4. 场景调用示例 | PDF、音频、视频、图片分别怎么传 |
| 5. 处理时间 | 要等多久、超时怎么设 |
| 6. Token 消耗 | usage 各字段含义与实测数据 |
| 7. 成本说明 | 怎么计费、怎么估算、怎么降本 |
| 错误码 · 用量查询 · Token 管理接口 | 排错与运维 |
1. 调用步骤
整体分 4 步:开通服务 → 创建 API Token → 选定版本 → 发起请求。
第 1 步:开通云点播服务
| 站点 | 控制台入口 |
|---|---|
| 国内站 | console.cloud.tencent.com/vod |
| 国际站 | tencentcloud.com/products/vod |
第 2 步:创建 API Token
方式一:控制台创建
- 进入云点播控制台 应用管理(国内站:应用管理),点击要使用的应用(SubAppId)。
- 在应用内依次进入 用量统计 → AIGC → AI 生文 → API Key 管理。
- 在弹窗中创建或删除 Key;点击「编辑」可按 Key 配置以下项:
| 配置项 | 说明 |
|---|---|
| 名称 | 展示在调用统计页面上,便于区分业务 |
| 模型白名单 | 全部模型,或只允许访问指定模型(多个用分号分隔) |
| IP 白名单 | 开启后只允许白名单内的 IP 调用(多个用分号分隔) |
| 额度限制 | 开启后按 Token 设置总额度,达到后无法继续调用 |
额度限制的两点注意
- 额度用量从启用额度功能时开始累计;关闭后重新启用,用量清零重新计算。
- 用量数据不是实时的,额度限制存在一定误差,无法与设置值完全精准一致。
方式二:接口创建
调用 CreateAigcApiToken(国内站文档 · 国际站文档),也可在 API Explorer 中直接生成:国内站 · 国际站。删除、查询、更新见 Token 管理接口。
使用须知
- Token 无过期时间,创建一次长期复用即可,无需每次调用都创建。
- 新建 Token 约需 1 分钟同步到网关,创建后立即使用可能返回
401。 - 国内站与国际站的 Token 不通用。
- 每个用户最多 50 个 Token,支持查询与删除。
- 与 VOD 文本网关共用同一 Token 池,已有 Token 可直接复用。
第 3 步:选定版本
三个版本调用同一端点,只有 model 字段不同。选型见 2. 版本差异。跑通第一次调用建议用 Flash:Pro 不支持纯文本请求。
第 4 步:发起请求
| 项 | 值 |
|---|---|
| Base URL | https://mmu.vod-qcloud.com/v1 |
| Full URL | https://mmu.vod-qcloud.com/v1/chat/completions |
| 请求方式 | POST |
| 协议 | OpenAI Chat Completions 兼容 |
OpenAI SDK(Python)
pip install openaifrom openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://mmu.vod-qcloud.com/v1",
)
response = client.chat.completions.create(
model="wand-vega-vl-1.0-flash",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hi, how are you?"},
],
extra_body={"reasoning_split": True}, # 可选:把思考内容与正文分开返回
)
msg = response.choices[0].message
# 带 reasoning_split 时,思考内容在 reasoning_details 中(未开思考时可能为空)
details = getattr(msg, "reasoning_details", None) or []
if details:
print(f"Thinking:\n{details[0]['text']}\n")
print(f"Text:\n{msg.content}\n")cURL(流式)
curl -X POST https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${API_KEY}" \
-d '{
"model": "wand-vega-vl-1.0-flash",
"stream": true,
"messages": [
{ "role": "user", "content": "hello" }
]
}'返回 200 且 choices[0].message.content 有内容,即接入完成。接下来把文本换成带素材的 Part 数组,见 4. 场景调用示例。
2. 版本差异
| 版本 | 模型 ID | 定位 | 适合场景 |
|---|---|---|---|
| Lite | wand-vega-vl-1.0-lite | 成本优先,面向轻量理解业务 | 短视频理解、海量图片分类、内容粗筛、高频低成本调用 |
| Flash | wand-vega-vl-1.0-flash | 均衡档,面向常规视频理解 | 数据打标、中等长度视频总结、脚本拆解等理解任务 |
| Pro | wand-vega-vl-1.0-pro | 效果优先,面向复杂任务 | 长视频理解、专业级点评、复杂理解任务 |
三个版本均支持全模态输入,接口协议、参数、响应结构完全一致。唯一的调用差异是 Pro 不支持纯文本请求,必须带至少一个分析素材。
| 版本 | 纯文本请求 | text | image | audio | file | video |
|---|---|---|---|---|---|---|
| Lite | ✅ 支持 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Flash | ✅ 支持 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Pro | ❌ 需与素材一并传入 | ✅ | ✅ | ✅ | ✅ | ✅ |
怎么选:先用 Flash 验证效果;量大、任务简单(分类、粗筛)时降到 Lite;长视频、需要细粒度点评或多步推理时升到 Pro。三者只改 model 字段,可以按任务路由到不同版本。
3. 关键入参与出参
请求头
| Header | 是否必需 | 说明 |
|---|---|---|
Authorization | 二选一 | Bearer ${TOKEN} |
x-api-key | 二选一 | ${TOKEN},不带 Bearer 前缀 |
Content-Type | 必需 | application/json |
X-Request-Id | 否 | 自定义请求 ID,便于问题追踪 |
Tx-User-Session-Id | 否 | 同一会话上下文带上相同值,后台按此映射到同一账号,提升缓存命中率、降低成本。对同一素材反复追问时务必固定 |
顶层请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | String | 是 | wand-vega-vl-1.0-lite / wand-vega-vl-1.0-flash / wand-vega-vl-1.0-pro |
messages | Array | 是 | 对话消息列表,见下文 |
stream | Boolean | 是 | 是否流式返回。true 逐段返回;false 生成完成后一次性返回 |
thinking_enabled | Boolean | 否 | 是否开启推理(CoT)。true 适合复杂逻辑,延迟增加并消耗 reasoning_tokens;false 为标准模式,响应更快 |
reasoning_effort | String | 否 | 思考等级:none / minimal / low / medium / high / xhigh。与 thinking_enabled 同时配置时以本字段为准 |
reasoning_split | Boolean | 否 | 把思考内容单独放进 message.reasoning_details,与正文分开。OpenAI SDK 需通过 extra_body 传入 |
temperature | Float | 否 | 随机性,0 ~ 2,默认约 0.7。提取、问答类任务建议调低 |
max_tokens | Integer | 否 | 单次请求最大 Token 数(含输入 + 输出),超出会截断或报错。视频输入动辄上万 Token,设置时要留足余量 |
max_completion_tokens | Integer | 否 | 同 max_tokens;两者同时存在时以 max_tokens 为准 |
response_format | Object | 否 | 结构化输出:text / json_object / json_schema,遵循 OpenAI 协议 |
tools / tool_choice | Array / Object | 否 | 工具调用,遵循 OpenAI 协议 |
messages 与 role
| 字段 | 类型 | 说明 |
|---|---|---|
role | String | system / developer(系统人设与规则)、user(提问与素材)、assistant(历史回答)、tool(工具结果) |
content | String 或 Array<Part> | 纯文本用字符串;带素材时用 Part 数组;role=tool 时为工具输出 |
tool_calls | Array | role=assistant 时,模型返回的待调用工具及参数 |
tool_call_id | String | role=tool 时,对应的工具调用 ID |
一般的分析请求只需要两条消息:system 写回答语言、格式、分析方式;user 写问题并附上素材。assistant / tool 仅在多轮追问或工具调用时使用。
content Part(多模态输入)
content 为数组时,每个元素是一个 Part,用 type 区分输入种类:
| type | 必填字段 | 说明 |
|---|---|---|
text | text | 问题或指令 |
image_url | image_url.url | 图片 URL 或 data URL;可选 image_url.detail 控制精细度 |
input_audio | input_audio | 二选一:① input_audio.url;② input_audio.data(Base64)+ input_audio.format(仅 mp3 / wav) |
video_url | video_url.url | 视频 URL 或 data URL |
file | file | 二选一:① file.file_url(可访问的 URL);② file.file_data(data:<mime>;base64,...)+ file.file_name |
已废弃字段
Part 顶层的 file_name、file_url 是 OpenAI 早期协议字段,官方已废弃,请改用 file 对象内的同名字段。
视频不要用 file 传
视频必须用 type: "video_url"。用 type: "file" 传视频会返回 502 + 502003(上游拒绝任务提交)。
媒体限制
| 项 | 限制 |
|---|---|
| 单个素材大小 | 建议 < 100 MB |
| 单次请求视频数 | 最多 10 个 |
| 素材可访问性 | URL 必须能被 API 服务器访问,建议海外可访问;私有存储请用在处理期间有效的签名 URL |
| 图片尺寸 | 最小 14px |
| 音频 Base64 格式 | 仅 mp3 / wav |
各版本入参差异
三个版本的请求参数完全相同,差别只在 model 取值与 content 能否为纯文本:
| 版本 | model | content 可为纯文本字符串 | 最少素材数 | 推荐的入门写法 |
|---|---|---|---|---|
| Lite | wand-vega-vl-1.0-lite | ✅ | 0 | 纯文本或任意素材 |
| Flash | wand-vega-vl-1.0-flash | ✅ | 0 | 纯文本或任意素材 |
| Pro | wand-vega-vl-1.0-pro | ❌ 必须为 Part 数组 | 1 | text Part + 至少 1 个图片 / 音频 / 文件 / 视频 Part |
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
id | String | 对话任务唯一标识 |
object | String | 固定为 chat.completion |
created | Integer | 响应创建时间戳(Unix 秒) |
model | String | 实际生成响应的模型版本 |
choices[].index | Integer | 结果索引 |
choices[].message.role | String | 固定为 assistant |
choices[].message.content | String | 核心返回:模型生成的文本回答 |
choices[].message.reasoning_content | String | 思考内容(thinking_enabled / reasoning_effort 生效时非空) |
choices[].message.reasoning_details | Array | 传 reasoning_split: true 时返回,思考文本在 [0].text |
choices[].message.tool_calls | Array | 工具调用信息,遵循 OpenAI 协议 |
choices[].finish_reason | String | 结束原因,stop 为正常结束 |
request_id | String | 顶层请求 ID,与响应头 X-Request-Id 一致,排查问题时提供 |
usage | Object | Token 用量,字段见 6. Token 消耗 |
返回示例(Flash,纯文本、开启思考):
{
"id": "vod_1306264703_00_sensev1_38f2416f...",
"object": "chat.completion",
"created": 1789476056,
"model": "wand-vega-vl1.0-flash",
"request_id": "01a0a515-7880-7cd7-bd7e-6af3a6feb5b4",
"choices": [
{
"index": 0,
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": "……模型回答……",
"reasoning_content": "……思考过程(开启思考时非空)……"
}
}
],
"usage": {
"prompt_tokens": 38,
"prompt_tokens_details": { "cached_tokens": 0, "cache_read_tokens": 0 },
"completion_tokens": 369,
"completion_tokens_details": { "reasoning_tokens": 318 },
"total_tokens": 407
}
}解析要点
- 正文读
choices[0].message.content;思考内容读reasoning_content,或在传了reasoning_split时读reasoning_details[0].text。 - JSON 类任务的
content可能被```json代码围栏包裹,用下面的解析器可同时处理两种形态,并建议保留原文以便追溯:
import json
def extract_json(text):
if not text:
return None
s = text.strip()
if s.startswith("```"):
s = s.strip("`")
if s.lower().startswith("json"):
s = s[4:]
s = s.strip()
try:
return json.loads(s)
except Exception:
start, end = s.find("{"), s.rfind("}")
if start == -1 or end <= start:
return None
try:
return json.loads(s[start:end + 1])
except Exception:
return None4. 场景调用示例
所有场景共用同一个结构:user 消息的 content 写成 Part 数组,放一个 text Part(指令)和一个或多个素材 Part。以下示例都可直接替换 model 在三个版本间切换(纯文本示例除外,Pro 不支持)。
| 场景 | 素材 Part | 示例版本 | 跳转 |
|---|---|---|---|
| 输入 PDF | file | Pro | PDF 文档分析 |
| 输入音频 | input_audio | Lite | 音频内容提取 |
| 输入视频 | video_url | Pro / Flash | 视频理解 · 精彩片段 JSON |
| 输入图片 | image_url | Flash / Pro | 图片分析 |
输入 PDF:文档分析
从文档中提取指定条目。PDF 用 file Part,可传 URL,也可传 Base64。
{
"model": "wand-vega-vl-1.0-pro",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "提取文档中记载的参考编号与账单金额。" },
{
"type": "file",
"file": { "file_url": "https://example.com/invoice.pdf" }
}
]
}
]
}示例文档的参考编号为 MAVORA,账单金额为 42 USD,结果在 choices[0].message.content 中返回。
用 Base64 传本地文件时,改为 file_data + file_name:
{
"type": "file",
"file": {
"file_data": "data:application/pdf;base64,<base64编码内容>",
"file_name": "invoice.pdf"
}
}输入音频:录音内容提取
{
"model": "wand-vega-vl-1.0-lite",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "提取录音中说出的暗号词和数字。" },
{
"type": "input_audio",
"input_audio": { "url": "https://example.com/record.mp3" }
}
]
}
]
}示例音频的暗号词为 lantern,数字为 43。用 Base64 传音频时改为 "input_audio": { "data": "<base64>", "format": "mp3" }(仅支持 mp3 / wav)。
输入视频:视频理解
视频用 video_url Part,单次请求最多 10 个视频。长视频建议开流式,边生成边展示。
{
"model": "wand-vega-vl-1.0-pro",
"stream": true,
"messages": [
{ "role": "system", "content": "你是一名专业的视频分析专家" },
{
"role": "user",
"content": [
{ "type": "text", "text": "这个视频讲了什么?" },
{
"type": "video_url",
"video_url": { "url": "https://example.com/video.mp4" }
}
]
}
]
}返回示例(视频为动画短片《Big Buck Bunny》):
{
"model": "wand-vega-vl-1.0-pro",
"choices": [
{
"index": 0,
"finish_reason": "stop",
"message": { "role": "assistant", "content": "这是《Big Buck Bunny》动画短片……" }
}
],
"usage": {
"prompt_tokens": 21375,
"prompt_tokens_details": { "cached_tokens": 0, "video_tokens": 21299, "audio_tokens": 0 },
"completion_tokens": 73,
"completion_tokens_details": { "reasoning_tokens": 0 },
"total_tokens": 21448
}
}输入视频:精彩片段提取(JSON 输出)
要结构化结果时,指定 response_format={"type":"json_object"},并在提示词里写清返回字段。示例素材是一段 10 秒的 Vega Pro 生成视频。
curl -sS https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Authorization: Bearer $AIGC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"response_format": { "type": "json_object" },
"messages": [
{
"role": "system",
"content": "仅分析视频中可确认的内容,并以有效 JSON 回答。"
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "总结这个视频的主要场景,并选出 1 个适合做短片的片段。开始与结束以秒为单位。回答格式:{\"summary\":\"场景总结\",\"highlights\":[{\"start\":0,\"end\":5,\"score\":80,\"reason\":\"选择理由\"}]}。score 为 0 到 100 之间的整数。"
},
{
"type": "video_url",
"video_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"
}
}
]
}
]
}'分析结果(content 解析后):
{
"summary": "视频中镜头沿着巧克力河的水面移动并逐渐升高,展现了一个遍布拐杖糖、漂浮的马卡龙和糖果搭成的巨大透明建筑的奇幻甜点世界,并记录了一位身穿饼干与糖果装饰的特别服装的女孩一边微笑走过、一边对周围景色发出赞叹的样子。",
"highlights": [
{
"start": 0,
"end": 10,
"score": 90,
"reason": "包含了整个奇幻甜点世界的景色和女孩愉快的反应,能用一个短片完整传达这个视频独特的童话氛围"
}
]
}同一写法可换成其他视频任务,只改 system 与返回结构:
| 任务 | system 提示词 | 返回结构 |
|---|---|---|
| 章节切分 | You are a video chaptering engine. Return strictly valid JSON, no prose. | {"duration_sec":<int>,"chapters":[{"start":"mm:ss","end":"mm:ss","title":"","summary":""}]} |
| 精彩片段 | You are a highlight detection engine for short-form clipping. Return strictly valid JSON, no prose. | {"highlights":[{"start":"mm:ss","end":"mm:ss","score":<0-100>,"reason":""}]} |
| 镜头分析 | You are a shot-breakdown engine. Return strictly valid JSON, no prose. | {"shots":[{"start":"mm:ss","end":"mm:ss","shot_type":"","camera":"","action":"","description":""}]} |
| 打标签 | You are a content tagging engine for a media catalogue. Return strictly valid JSON, no prose. | {"categories":[],"tags":[],"keywords":[],"mood":[],"objects":[],"safe_for_work":<true|false>} |
| 画面文字 | You are an OCR engine for video frames. Return strictly valid JSON, no prose. | {"texts":[{"time":"mm:ss","text":"","kind":"subtitle|signage|ui|other"}]} |
| 内容审核 | You are a content moderation reviewer. Return strictly valid JSON, no prose. | {"risk_level":"low|medium|high","categories":[],"evidence":[{"time":"mm:ss","reason":""}],"verdict":""} |
| 分发元数据 | You are a publishing metadata generator for a VOD catalogue. Return strictly valid JSON, no prose. | {"title":"","logline":"","description":"","tags":[],"category":"","thumbnail_timecode":"mm:ss"} |
| 语音转写(文本) | You are a transcription engine. Transcribe spoken content faithfully. | 每条发言一行 [mm:ss] speaker: text;无声输入返回 NO_SPEECH |
JSON 任务建议在指令末尾追加 Respond with JSON only.,并把返回结构写在 user 指令里,输出更稳定。
输入图片:图片分析
图片可传 URL,也可传 Base64 data URL:
{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "请分析这张图片" },
{
"type": "image_url",
"image_url": { "url": "data:image/jpeg;base64,<base64编码内容>" }
}
]
}
]
}图片打标签并返回 JSON(Pro,Python):
import requests
ENDPOINT = "https://mmu.vod-qcloud.com/v1/chat/completions"
TOKEN = "<VOD AIGC Token>"
body = {
"model": "wand-vega-vl-1.0-pro",
"stream": False,
"response_format": {"type": "json_object"},
"messages": [
{"role": "user", "content": [
{"type": "text", "text": "为这张图片提取标签。Respond with JSON only."},
{"type": "image_url", "image_url": {"url": "https://example.com/frame.jpg"}},
]},
],
}
r = requests.post(ENDPOINT, json=body,
headers={"Authorization": f"Bearer {TOKEN}"}, timeout=600)
content = r.json()["choices"][0]["message"]["content"]
print(extract_json(content)) # extract_json 见「返回参数 → 解析要点」一次请求可以混合多种素材,例如「一张关键帧 + 一段视频」:在同一个 content 数组里依次放 text、image_url、video_url 三个 Part 即可。
5. 处理时间
| 输入 | 实测处理时间 |
|---|---|
| 短片(约 6 秒) | 10 ~ 50 秒 |
| 长视频 | 数分钟 |
- 处理时间主要取决于视频时长与数量,其次是是否开启思考(
thinking_enabled/reasoning_effort会增加延迟)。 stream=false时,响应会在全部生成完成后一次性返回,HTTP 客户端超时请设为600秒。- 需要尽快展示结果时用
stream=true,首段内容会更早到达,总耗时不变。 - 刚创建的 Token 约 1 分钟后才生效,这段时间的
401不计入处理时间问题。
6. Token 消耗
usage 字段
| 字段 | 说明 |
|---|---|
prompt_tokens | 输入总 Token(文本 + 图片 + 音频 + 文件 + 视频) |
prompt_tokens_details.cached_tokens | 输入中命中缓存的 Token |
prompt_tokens_details.cache_read_tokens | 输入中从缓存读取的 Token,命中越多越省钱 |
video_tokens | 含视频输入时视频消耗的 Token |
prompt_tokens_details.audio_tokens | 含音频时音频消耗的 Token |
completion_tokens | 输出总 Token(含思考 Token) |
completion_tokens_details.reasoning_tokens | 输出中的思考 Token,未开思考时为 0 |
total_tokens | 输入 + 输出总 Token |
video_tokens 可能在 usage 顶层,也可能在 usage.prompt_tokens_details 下(以上两个示例分别如此),读取时请做回退:
video_tokens = usage.get("video_tokens") or (usage.get("prompt_tokens_details") or {}).get("video_tokens")实测消耗
| 场景 | 版本 | 输入 | 其中视频 | 输出 | 其中思考 | 合计 |
|---|---|---|---|---|---|---|
| 纯文本、开启思考 | Flash | 38 | — | 369 | 318 | 407 |
| 视频理解(《Big Buck Bunny》) | Pro | 21,375 | 21,299 | 73 | 0 | 21,448 |
从这两组数据可以看出消耗的结构:
- 视频输入是大头:视频请求里
video_tokens占输入的 99.6%(21,299 / 21,375),文本指令几乎可以忽略。视频 Token 随视频时长与数量增长。 - 思考 Token 计入输出:开启思考后,纯文本示例的 369 个输出 Token 中有 318 个(86%)是思考过程。简单的提取、分类任务关闭思考可显著减少输出。
max_tokens包含输入:带视频请求时如果max_tokens设得比视频 Token 还小,请求会被截断或报错。
7. 成本说明
Vega VL 按 Token 后付费,在云点播 AIGC 生文(大模型文本处理) 计费项下出账。每次请求按返回的 usage 分别计量输入、缓存命中、输出三部分。AIGC 生文目前不支持资源包抵扣。
刊例价
| 模型版本 | 国内站 输入 (元 / 百万 tokens) | 国内站 输出 | 国内站 缓存命中 | 国际站 输入 (USD / 百万 tokens) | 国际站 输出 | 国际站 缓存命中 |
|---|---|---|---|---|---|---|
wand-vega-vl-1.0-lite | 0.7 | 2.6 | 0.14 | 0.14 | 0.45 | 0.028 |
wand-vega-vl-1.0-flash | 3 | 15 | 0.6 | 0.44 | 2.21 | 0.088 |
wand-vega-vl-1.0-pro | 8 | 40 | 1 | 1.25 | 6.25 | 0.15 |
- 价格截至 2026-11-15,以官网刊例与控制台账单为准。
- 输出单价约为输入的 3.2 ~ 5 倍;缓存命中单价为输入的 20%(Lite / Flash)或约 12%(Pro)。
- 思考 Token(
reasoning_tokens)计入completion_tokens,按输出单价计费。
估算公式
单次费用 = (prompt_tokens − cached_tokens) × 输入单价
+ cached_tokens × 缓存命中单价
+ completion_tokens × 输出单价
(单价为「每百万 tokens」,结果再除以 1,000,000)费用示例
参考值
以下按上文实测消耗的 usage 与刊例价计算,用来看量级。实际费用随素材时长、提示词与输出长度变化,以账单为准。
视频理解(输入 21,375 / 其中视频 21,299 / 输出 73 Tokens,无缓存):
| 版本 | 国内站 单次 | 国内站 每 1,000 次 | 国际站 单次 | 国际站 每 1,000 次 |
|---|---|---|---|---|
| Lite | ¥0.0152 | ¥15.15 | $0.0030 | $3.03 |
| Flash | ¥0.0652 | ¥65.22 | $0.0096 | $9.57 |
| Pro | ¥0.1739 | ¥173.92 | $0.0272 | $27.18 |
输入侧占了费用的 98% 以上,视频时长决定成本量级;输出只有几十个 Token,影响很小。
同一视频重复追问、视频部分命中缓存(假设 21,299 个视频 Token 全部命中缓存,其余不变):
| 版本 | 国内站 每 1,000 次 | 国际站 每 1,000 次 | 较无缓存节省 |
|---|---|---|---|
| Lite | ¥3.22 | $0.64 | 约 79% |
| Flash | ¥14.10 | $2.07 | 约 78% |
| Pro | ¥24.83 | $3.75 | 约 86% |
降本手段
| 手段 | 作用于 | 说明 |
|---|---|---|
| 选低档版本 | 单价 | 同一视频示例,Lite 的费用约为 Pro 的 1/11。分类、粗筛、高频调用用 Lite,复杂任务才用 Pro |
固定 Tx-User-Session-Id | 缓存命中 | 对同一素材多次追问时带相同会话 ID,命中部分按缓存价计费,体现在 cached_tokens / cache_read_tokens 上 |
| 一次请求问完 | 输入 | 同一视频的摘要、章节、标签尽量合并在一条指令里,避免重复传入同一段视频 |
| 裁剪素材 | 输入 | 只传需要分析的片段,视频 Token 随时长增长 |
| 关闭思考 | 输出 | 简单任务不开 thinking_enabled,或设 reasoning_effort: "none" / "minimal";思考 Token 按输出价计费 |
| 按 Key 设额度 | 风控 | 在 API Key 管理里为每个 Key 设额度上限,防止异常调用 |
账单可在 用量统计 → AIGC → AI 生文查看,或调用 DescribeAigcUsageData,见用量查询。
错误码
| HTTP 状态码 | 含义 |
|---|---|
200 | 成功 |
400 | 请求参数错误 |
401 | 认证失败(Token 无效) |
403 | 权限不足或已停服(如欠费) |
404 | 模型或端点不存在(如 model 名不支持、路径错误) |
429 | 触发限速 |
5xx | 服务器 / 上游错误。如用 type: "file" 传视频会返回 502 + 502003 |
每个错误响应都会返回具体错误信息与 request_id;每个响应头都带 X-Request-Id,便于排查。错误响应结构:
{
"error": {
"code": "404001",
"message": "model not found: xxx",
"type": "CodeModelNotExist",
"param": null
},
"request_id": "01a0a52a-..."
}| 错误码 | type | 常见原因 |
|---|---|---|
401001 | CodeAuthFailed | Key 无效,或刚创建还未同步到网关(约 1 分钟) |
404001 | CodeModelNotExist | model 名写错 |
502003 | CodeUpstreamError | 上游参数错误,如视频传参方式不对 |
用量查询
控制台查看
| 范围 | 入口 |
|---|---|
| 账号整体用量 | 云点播控制台 用量统计 → AIGC → 「AI 生文」 |
| 指定 SubAppId 用量 | 应用管理(国内站:应用管理) → 点击应用 → 用量统计 → AIGC → 「AI 生文」 |
| 按 API Key 调用统计 | 调用统计 · 可视化,Key 的「名称」会展示在这里 |
| 请求明细日志 | 请求日志 · 查询 |
接口查询
| 站点 | 接口 |
|---|---|
| 国内站 | 查询 AIGC 用量统计数据 |
| 国际站 | DescribeAigcUsageData |
Token 管理接口
| 操作 | 接口 | 文档 |
|---|---|---|
| 创建 | CreateAigcApiToken | 国内站 · 国际站 |
| 删除 | DeleteAigcApiToken | 国内站 · 国际站 |
| 查询 | DescribeAigcApiTokens | 国内站 · 国际站 |
| 更新 | UpdateAigcApiToken | 国内站 Explorer · 国际站 Explorer |