跳到内容

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 ​

方式一:控制台创建

  1. 进入云点播控制台 应用管理(国内站:应用管理),点击要使用的应用(SubAppId)。
  2. 在应用内依次进入 用量统计 → AIGC → AI 生文 → API Key 管理。
  3. 在弹窗中创建或删除 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 URLhttps://mmu.vod-qcloud.com/v1
Full URLhttps://mmu.vod-qcloud.com/v1/chat/completions
请求方式POST
协议OpenAI Chat Completions 兼容

OpenAI SDK(Python)

bash
pip install openai
python
from 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(流式)

bash
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定位适合场景
Litewand-vega-vl-1.0-lite成本优先,面向轻量理解业务短视频理解、海量图片分类、内容粗筛、高频低成本调用
Flashwand-vega-vl-1.0-flash均衡档,面向常规视频理解数据打标、中等长度视频总结、脚本拆解等理解任务
Prowand-vega-vl-1.0-pro效果优先,面向复杂任务长视频理解、专业级点评、复杂理解任务

三个版本均支持全模态输入,接口协议、参数、响应结构完全一致。唯一的调用差异是 Pro 不支持纯文本请求,必须带至少一个分析素材。

版本纯文本请求textimageaudiofilevideo
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否同一会话上下文带上相同值,后台按此映射到同一账号,提升缓存命中率、降低成本。对同一素材反复追问时务必固定

顶层请求参数 ​

参数类型必填说明
modelString是wand-vega-vl-1.0-lite / wand-vega-vl-1.0-flash / wand-vega-vl-1.0-pro
messagesArray是对话消息列表,见下文
streamBoolean是是否流式返回。true 逐段返回;false 生成完成后一次性返回
thinking_enabledBoolean否是否开启推理(CoT)。true 适合复杂逻辑,延迟增加并消耗 reasoning_tokens;false 为标准模式,响应更快
reasoning_effortString否思考等级:none / minimal / low / medium / high / xhigh。与 thinking_enabled 同时配置时以本字段为准
reasoning_splitBoolean否把思考内容单独放进 message.reasoning_details,与正文分开。OpenAI SDK 需通过 extra_body 传入
temperatureFloat否随机性,0 ~ 2,默认约 0.7。提取、问答类任务建议调低
max_tokensInteger否单次请求最大 Token 数(含输入 + 输出),超出会截断或报错。视频输入动辄上万 Token,设置时要留足余量
max_completion_tokensInteger否同 max_tokens;两者同时存在时以 max_tokens 为准
response_formatObject否结构化输出:text / json_object / json_schema,遵循 OpenAI 协议
tools / tool_choiceArray / Object否工具调用,遵循 OpenAI 协议

messages 与 role ​

字段类型说明
roleStringsystem / developer(系统人设与规则)、user(提问与素材)、assistant(历史回答)、tool(工具结果)
contentString 或 Array<Part>纯文本用字符串;带素材时用 Part 数组;role=tool 时为工具输出
tool_callsArrayrole=assistant 时,模型返回的待调用工具及参数
tool_call_idStringrole=tool 时,对应的工具调用 ID

一般的分析请求只需要两条消息:system 写回答语言、格式、分析方式;user 写问题并附上素材。assistant / tool 仅在多轮追问或工具调用时使用。

content Part(多模态输入) ​

content 为数组时,每个元素是一个 Part,用 type 区分输入种类:

type必填字段说明
texttext问题或指令
image_urlimage_url.url图片 URL 或 data URL;可选 image_url.detail 控制精细度
input_audioinput_audio二选一:① input_audio.url;② input_audio.data(Base64)+ input_audio.format(仅 mp3 / wav)
video_urlvideo_url.url视频 URL 或 data URL
filefile二选一:① 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 能否为纯文本:

版本modelcontent 可为纯文本字符串最少素材数推荐的入门写法
Litewand-vega-vl-1.0-lite✅0纯文本或任意素材
Flashwand-vega-vl-1.0-flash✅0纯文本或任意素材
Prowand-vega-vl-1.0-pro❌ 必须为 Part 数组1text Part + 至少 1 个图片 / 音频 / 文件 / 视频 Part

返回参数 ​

参数类型说明
idString对话任务唯一标识
objectString固定为 chat.completion
createdInteger响应创建时间戳(Unix 秒)
modelString实际生成响应的模型版本
choices[].indexInteger结果索引
choices[].message.roleString固定为 assistant
choices[].message.contentString核心返回:模型生成的文本回答
choices[].message.reasoning_contentString思考内容(thinking_enabled / reasoning_effort 生效时非空)
choices[].message.reasoning_detailsArray传 reasoning_split: true 时返回,思考文本在 [0].text
choices[].message.tool_callsArray工具调用信息,遵循 OpenAI 协议
choices[].finish_reasonString结束原因,stop 为正常结束
request_idString顶层请求 ID,与响应头 X-Request-Id 一致,排查问题时提供
usageObjectToken 用量,字段见 6. Token 消耗

返回示例(Flash,纯文本、开启思考):

json
{
  "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 代码围栏包裹,用下面的解析器可同时处理两种形态,并建议保留原文以便追溯:
python
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 None

4. 场景调用示例 ​

所有场景共用同一个结构:user 消息的 content 写成 Part 数组,放一个 text Part(指令)和一个或多个素材 Part。以下示例都可直接替换 model 在三个版本间切换(纯文本示例除外,Pro 不支持)。

场景素材 Part示例版本跳转
输入 PDFfileProPDF 文档分析
输入音频input_audioLite音频内容提取
输入视频video_urlPro / Flash视频理解 · 精彩片段 JSON
输入图片image_urlFlash / Pro图片分析

输入 PDF:文档分析 ​

从文档中提取指定条目。PDF 用 file Part,可传 URL,也可传 Base64。

json
{
  "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:

json
{
  "type": "file",
  "file": {
    "file_data": "data:application/pdf;base64,<base64编码内容>",
    "file_name": "invoice.pdf"
  }
}

输入音频:录音内容提取 ​

json
{
  "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 个视频。长视频建议开流式,边生成边展示。

json
{
  "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》):

json
{
  "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 生成视频。

bash
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 解析后):

json
{
  "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:

json
{
  "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):

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 下(以上两个示例分别如此),读取时请做回退:

python
video_tokens = usage.get("video_tokens") or (usage.get("prompt_tokens_details") or {}).get("video_tokens")

实测消耗 ​

场景版本输入其中视频输出其中思考合计
纯文本、开启思考Flash38—369318407
视频理解(《Big Buck Bunny》)Pro21,37521,29973021,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-lite0.72.60.140.140.450.028
wand-vega-vl-1.0-flash3150.60.442.210.088
wand-vega-vl-1.0-pro84011.256.250.15
  • 价格截至 2026-11-15,以官网刊例与控制台账单为准。
  • 输出单价约为输入的 3.2 ~ 5 倍;缓存命中单价为输入的 20%(Lite / Flash)或约 12%(Pro)。
  • 思考 Token(reasoning_tokens)计入 completion_tokens,按输出单价计费。

估算公式 ​

text
单次费用 = (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,便于排查。错误响应结构:

json
{
  "error": {
    "code": "404001",
    "message": "model not found: xxx",
    "type": "CodeModelNotExist",
    "param": null
  },
  "request_id": "01a0a52a-..."
}
错误码type常见原因
401001CodeAuthFailedKey 无效,或刚创建还未同步到网关(约 1 分钟)
404001CodeModelNotExistmodel 名写错
502003CodeUpstreamError上游参数错误,如视频传参方式不对

用量查询 ​

控制台查看 ​

范围入口
账号整体用量云点播控制台 用量统计 → AIGC → 「AI 生文」
指定 SubAppId 用量应用管理(国内站:应用管理) → 点击应用 → 用量统计 → AIGC → 「AI 生文」
按 API Key 调用统计调用统计 · 可视化,Key 的「名称」会展示在这里
请求明细日志请求日志 · 查询

接口查询 ​

站点接口
国内站查询 AIGC 用量统计数据
国际站DescribeAigcUsageData

Token 管理接口 ​

操作接口文档
创建CreateAigcApiToken国内站 · 国际站
删除DeleteAigcApiToken国内站 · 国际站
查询DescribeAigcApiTokens国内站 · 国际站
更新UpdateAigcApiToken国内站 Explorer · 国际站 Explorer

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages