Vega VL HOT โ
- Endpoint:
https://mmu.vod-qcloud.com/v1/chat/completions - Authentication: VOD AIGC API Token (
Authorization: Bearerorx-api-key) - Protocol: OpenAI Chat Completions compatible โ works with the OpenAI SDK as is
Vega-VL is WAND's multimodal understanding model (VL = Vision-Language). It analyzes text, images, audio, files (PDF and similar), and video, and returns results as text or JSON. Typical uses: video summaries, chaptering, highlight extraction, on-screen text recognition, image tagging, extracting content from recordings, and document Q&A.
This page follows the order you integrate in:
| Section | Answers |
|---|---|
| 1. Integration steps | What to do from activation to your first successful call |
| 2. Version differences | How to choose between Lite, Flash, and Pro |
| 3. Key parameters and response fields | How to build the request and read the response, and what differs by version |
| 4. Scenario examples | How to pass a PDF, audio, video, or image |
| 5. Processing time | How long to wait and how to set timeouts |
| 6. Token consumption | What each usage field means, with measured data |
| 7. Cost | How billing works, how to estimate, and how to save |
| Error codes ยท Usage lookup ยท Token management APIs | Troubleshooting and operations |
1. Integration steps โ
Four steps: activate the service โ create an API token โ pick a version โ send a request.
Step 1: Activate VOD โ
| Site | Console |
|---|---|
| China site | console.cloud.tencent.com/vod |
| International site | tencentcloud.com/products/vod |
Step 2: Create an API token โ
Option 1: in the console
- Open Application Management in the VOD console (China site: Application Management) and click the application (SubAppId) you want to use.
- Inside the application, go to Usage Statistics โ AIGC โ AI Text โ API Key Management.
- Create or delete keys in the dialog. Click Edit to configure each key:
| Setting | Description |
|---|---|
| Name | Shown on the call statistics page so you can tell workloads apart |
| Model allowlist | All models, or only the listed models (separate multiple with semicolons) |
| IP allowlist | When enabled, only listed IPs can call (separate multiple with semicolons) |
| Quota | When enabled, sets a total token quota; calls stop once it is reached |
Two notes on quotas
- Quota usage starts counting when the quota is enabled. Disabling and re-enabling it resets usage to zero.
- Usage data is not real time, so the quota is enforced with some lag and cannot match the configured value exactly.
Option 2: via API
Call CreateAigcApiToken (China site docs ยท International site docs), or generate one directly in API Explorer: China site ยท International site. For delete, describe, and update, see Token management APIs.
Notes
- Tokens do not expire. Create one and reuse it; there is no need to create a token per call.
- A new token takes about 1 minute to sync to the gateway; using it immediately may return
401. - Tokens are not interchangeable between the China and International sites.
- Each user can hold up to 50 tokens; tokens can be listed and deleted.
- Vega VL shares the token pool with the VOD text gateway, so existing tokens work as is.
Step 3: Pick a version โ
All three versions use the same endpoint; only the model field differs. See 2. Version differences. Use Flash for your first call โ Pro does not accept text-only requests.
Step 4: Send a request โ
| Item | Value |
|---|---|
| Base URL | https://mmu.vod-qcloud.com/v1 |
| Full URL | https://mmu.vod-qcloud.com/v1/chat/completions |
| Method | POST |
| Protocol | OpenAI Chat Completions compatible |
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}, # optional: return reasoning separately from the answer
)
msg = response.choices[0].message
# With reasoning_split, reasoning is in reasoning_details (may be empty when thinking is off)
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 (streaming)
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" }
]
}'If you get 200 and choices[0].message.content has text, integration is done. Next, replace the text with a Part array that carries your material โ see 4. Scenario examples.
2. Version differences โ
| Version | Model ID | Positioning | Best for |
|---|---|---|---|
| Lite | wand-vega-vl-1.0-lite | Cost first, for lightweight understanding | Short-video understanding, high-volume image classification, coarse content screening, frequent low-cost calls |
| Flash | wand-vega-vl-1.0-flash | Balanced, for everyday video understanding | Data labeling, summarizing mid-length videos, script breakdowns |
| Pro | wand-vega-vl-1.0-pro | Quality first, for complex tasks | Long-video understanding, professional-grade reviews, complex understanding tasks |
All three versions accept every modality, and the protocol, parameters, and response structure are identical. The only calling difference is that Pro does not accept text-only requests โ it needs at least one piece of material.
| Version | Text-only request | text | image | audio | file | video |
|---|---|---|---|---|---|---|
| Lite | โ Supported | โ | โ | โ | โ | โ |
| Flash | โ Supported | โ | โ | โ | โ | โ |
| Pro | โ Must include material | โ | โ | โ | โ | โ |
How to choose: validate quality with Flash first. Drop to Lite for high volume and simple tasks (classification, screening); move up to Pro for long videos, fine-grained reviews, or multi-step reasoning. Only model changes, so you can route tasks to different versions.
3. Key parameters and response fields โ
Request headers โ
| Header | Required | Description |
|---|---|---|
Authorization | One of the two | Bearer ${TOKEN} |
x-api-key | One of the two | ${TOKEN}, without the Bearer prefix |
Content-Type | Required | application/json |
X-Request-Id | No | Your own request ID, for tracing |
Tx-User-Session-Id | No | Send the same value within one conversation context; the backend maps it to the same account, raising the cache hit rate and lowering cost. Keep it fixed when asking repeated questions about the same material |
Top-level request parameters โ
| Parameter | Type | Required | Description |
|---|---|---|---|
model | String | Yes | wand-vega-vl-1.0-lite / wand-vega-vl-1.0-flash / wand-vega-vl-1.0-pro |
messages | Array | Yes | Conversation messages, see below |
stream | Boolean | Yes | Streaming. true returns chunks as they are generated; false returns everything at the end |
thinking_enabled | Boolean | No | Enables reasoning (CoT). true suits complex logic but adds latency and consumes reasoning_tokens; false is standard mode and faster |
reasoning_effort | String | No | Reasoning level: none / minimal / low / medium / high / xhigh. Takes precedence over thinking_enabled when both are set |
reasoning_split | Boolean | No | Puts reasoning in message.reasoning_details, separate from the answer. With the OpenAI SDK, pass it via extra_body |
temperature | Float | No | Randomness, 0 ~ 2, default about 0.7. Lower it for extraction and Q&A |
max_tokens | Integer | No | Maximum tokens per request (input + output); exceeding it truncates or errors. Video input easily reaches tens of thousands of tokens, so leave headroom |
max_completion_tokens | Integer | No | Same as max_tokens; max_tokens wins when both are set |
response_format | Object | No | Structured output: text / json_object / json_schema, per the OpenAI protocol |
tools / tool_choice | Array / Object | No | Tool calling, per the OpenAI protocol |
messages and role โ
| Field | Type | Description |
|---|---|---|
role | String | system / developer (persona and rules), user (question and material), assistant (earlier answers), tool (tool results) |
content | String or Array<Part> | A string for text only; a Part array when sending material; the tool output when role=tool |
tool_calls | Array | With role=assistant, the tools the model wants to call and their arguments |
tool_call_id | String | With role=tool, the ID of the tool call this result belongs to |
A typical analysis request needs just two messages: system sets the answer language, format, and approach; user carries the question plus material. Use assistant / tool only for multi-turn follow-ups or tool calling.
content Parts (multimodal input) โ
When content is an array, each element is a Part, identified by type:
| type | Required field | Description |
|---|---|---|
text | text | Question or instruction |
image_url | image_url.url | Image URL or data URL; optional image_url.detail controls fidelity |
input_audio | input_audio | Either โ input_audio.url, or โก input_audio.data (Base64) + input_audio.format (mp3 / wav only) |
video_url | video_url.url | Video URL or data URL |
file | file | Either โ file.file_url (a reachable URL), or โก file.file_data (data:<mime>;base64,...) + file.file_name |
Deprecated fields
file_name and file_url at the top level of a Part are early OpenAI protocol fields and are deprecated. Use the fields of the same name inside the file object.
Do not send video as file
Video must use type: "video_url". Sending video with type: "file" returns 502 + 502003 (upstream rejected the task).
Media limits โ
| Item | Limit |
|---|---|
| Size per item | Recommended < 100 MB |
| Videos per request | Up to 10 |
| Reachability | URLs must be reachable by the API server, ideally from outside mainland China; for private storage, use a signed URL valid for the whole processing time |
| Image size | At least 14px |
| Base64 audio format | mp3 / wav only |
Parameter differences by version โ
Request parameters are identical across versions; the only differences are the model value and whether content may be plain text:
| Version | model | content may be a plain string | Minimum material | Suggested first request |
|---|---|---|---|---|
| Lite | wand-vega-vl-1.0-lite | โ | 0 | Text only or any material |
| Flash | wand-vega-vl-1.0-flash | โ | 0 | Text only or any material |
| Pro | wand-vega-vl-1.0-pro | โ Must be a Part array | 1 | A text Part + at least one image / audio / file / video Part |
Response fields โ
| Field | Type | Description |
|---|---|---|
id | String | Unique ID of the completion |
object | String | Always chat.completion |
created | Integer | Creation time (Unix seconds) |
model | String | The model version that produced the response |
choices[].index | Integer | Result index |
choices[].message.role | String | Always assistant |
choices[].message.content | String | Main output: the model's text answer |
choices[].message.reasoning_content | String | Reasoning (non-empty when thinking_enabled / reasoning_effort is in effect) |
choices[].message.reasoning_details | Array | Returned with reasoning_split: true; reasoning text is in [0].text |
choices[].message.tool_calls | Array | Tool calls, per the OpenAI protocol |
choices[].finish_reason | String | Why generation stopped; stop is a normal finish |
request_id | String | Top-level request ID, same as the X-Request-Id response header; include it when reporting issues |
usage | Object | Token usage; see 6. Token consumption |
Sample response (Flash, text only, reasoning on):
{
"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": "...model answer...",
"reasoning_content": "...reasoning (non-empty when thinking is on)..."
}
}
],
"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
}
}Parsing tips
- Read the answer from
choices[0].message.content; read reasoning fromreasoning_content, or fromreasoning_details[0].textwhen you sentreasoning_split. - For JSON tasks,
contentmay come wrapped in a```jsonfence. The parser below handles both forms; keep the raw text too, for traceability:
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. Scenario examples โ
Every scenario uses the same shape: the user message's content is a Part array with one text Part (the instruction) and one or more material Parts. You can switch versions in any example by changing model (except text-only requests, which Pro does not accept).
| Scenario | Material Part | Version in example | Jump to |
|---|---|---|---|
| PDF input | file | Pro | PDF document analysis |
| Audio input | input_audio | Lite | Extracting content from a recording |
| Video input | video_url | Pro / Flash | Video understanding ยท Highlights as JSON |
| Image input | image_url | Flash / Pro | Image analysis |
PDF input: document analysis โ
Extract specific items from a document. PDFs use the file Part, by URL or Base64.
{
"model": "wand-vega-vl-1.0-pro",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Extract the reference code and billed amount stated in the document." },
{
"type": "file",
"file": { "file_url": "https://example.com/invoice.pdf" }
}
]
}
]
}The sample document's reference code is MAVORA and the billed amount is 42 USD; the result comes back in choices[0].message.content.
To send a local file as Base64, use file_data + file_name instead:
{
"type": "file",
"file": {
"file_data": "data:application/pdf;base64,<base64 content>",
"file_name": "invoice.pdf"
}
}Audio input: extracting content from a recording โ
{
"model": "wand-vega-vl-1.0-lite",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Extract the code word and number spoken in the recording." },
{
"type": "input_audio",
"input_audio": { "url": "https://example.com/record.mp3" }
}
]
}
]
}The sample recording's code word is lantern and the number is 43. To send audio as Base64, use "input_audio": { "data": "<base64>", "format": "mp3" } (mp3 / wav only).
Video input: video understanding โ
Video uses the video_url Part, up to 10 videos per request. Turn on streaming for long videos so output appears as it is generated.
{
"model": "wand-vega-vl-1.0-pro",
"stream": true,
"messages": [
{ "role": "system", "content": "You are a professional video analyst." },
{
"role": "user",
"content": [
{ "type": "text", "text": "What is this video about?" },
{
"type": "video_url",
"video_url": { "url": "https://example.com/video.mp4" }
}
]
}
]
}Sample response (the video is the animated short Big Buck Bunny):
{
"model": "wand-vega-vl-1.0-pro",
"choices": [
{
"index": 0,
"finish_reason": "stop",
"message": { "role": "assistant", "content": "This is the animated short 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
}
}Video input: highlight extraction (JSON output) โ
For structured results, set response_format={"type":"json_object"} and spell out the fields in the prompt. The sample is a 10-second video generated by 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": "Analyze only what can be confirmed in the video and answer in valid JSON."
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Summarize the main scenes of this video and pick 1 segment suitable for a short clip. Start and end are in seconds. Response format: {\"summary\":\"scene summary\",\"highlights\":[{\"start\":0,\"end\":5,\"score\":80,\"reason\":\"why it was picked\"}]}. score is an integer from 0 to 100."
},
{
"type": "video_url",
"video_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"
}
}
]
}
]
}'Result (after parsing content):
{
"summary": "The camera glides along the surface of a chocolate river and gradually rises, revealing a fantastical dessert world filled with candy canes, floating macarons, and huge transparent buildings made of candy, and follows a smiling girl in a special outfit decorated with cookies and candy as she walks along, marveling at the scenery around her.",
"highlights": [
{
"start": 0,
"end": 10,
"score": 90,
"reason": "It contains both the whole fantasy dessert landscape and the girl's delighted reaction, so a single short clip can fully convey the video's unique fairy-tale mood."
}
]
}The same pattern covers other video tasks โ change only the system prompt and the return structure:
| Task | system prompt | Return structure |
|---|---|---|
| Chaptering | You are a video chaptering engine. Return strictly valid JSON, no prose. | {"duration_sec":<int>,"chapters":[{"start":"mm:ss","end":"mm:ss","title":"","summary":""}]} |
| Highlights | 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":""}]} |
| Shot breakdown | You are a shot-breakdown engine. Return strictly valid JSON, no prose. | {"shots":[{"start":"mm:ss","end":"mm:ss","shot_type":"","camera":"","action":"","description":""}]} |
| Tagging | 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>} |
| On-screen text | You are an OCR engine for video frames. Return strictly valid JSON, no prose. | {"texts":[{"time":"mm:ss","text":"","kind":"subtitle|signage|ui|other"}]} |
| Moderation | You are a content moderation reviewer. Return strictly valid JSON, no prose. | {"risk_level":"low|medium|high","categories":[],"evidence":[{"time":"mm:ss","reason":""}],"verdict":""} |
| Publishing metadata | 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"} |
| Transcript (text) | You are a transcription engine. Transcribe spoken content faithfully. | One line per utterance, [mm:ss] speaker: text; silent input returns NO_SPEECH |
For JSON tasks, end the instruction with Respond with JSON only. and keep the return structure in the user instruction for more stable output.
Image input: image analysis โ
Images can be a URL or a Base64 data URL:
{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Analyze this image." },
{
"type": "image_url",
"image_url": { "url": "data:image/jpeg;base64,<base64 content>" }
}
]
}
]
}Tagging an image with JSON output (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": "Extract tags for this image. 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: see "Response fields โ Parsing tips"A single request can mix materials, for example a key frame plus a video: put text, image_url, and video_url Parts in the same content array.
5. Processing time โ
| Input | Measured processing time |
|---|---|
| Short clip (about 6 seconds) | 10 โ 50 seconds |
| Long video | Several minutes |
- Processing time depends mainly on video length and count, and then on whether reasoning is on (
thinking_enabled/reasoning_effortadd latency). - With
stream=false, the response arrives in one piece after generation finishes, so set your HTTP client timeout to600seconds. - Use
stream=trueto show results sooner; the first chunk arrives earlier, though total time is the same. - A newly created token takes about 1 minute to become active;
401errors during that window are not a processing-time issue.
6. Token consumption โ
usage fields โ
| Field | Description |
|---|---|
prompt_tokens | Total input tokens (text + image + audio + file + video) |
prompt_tokens_details.cached_tokens | Input tokens that hit the cache |
prompt_tokens_details.cache_read_tokens | Input tokens read from the cache; more hits means lower cost |
video_tokens | Tokens consumed by video input |
prompt_tokens_details.audio_tokens | Tokens consumed by audio input |
completion_tokens | Total output tokens (including reasoning) |
completion_tokens_details.reasoning_tokens | Reasoning tokens within the output; 0 when reasoning is off |
total_tokens | Input + output tokens |
video_tokens can appear at the top level of usage or under usage.prompt_tokens_details (the docs show both), so read it with a fallback:
video_tokens = usage.get("video_tokens") or (usage.get("prompt_tokens_details") or {}).get("video_tokens")Measured consumption โ
| Scenario | Version | Input | of which video | Output | of which reasoning | Total |
|---|---|---|---|---|---|---|
| Text only, reasoning on | Flash | 38 | โ | 369 | 318 | 407 |
| Video understanding (Big Buck Bunny) | Pro | 21,375 | 21,299 | 73 | 0 | 21,448 |
What the two samples show:
- Video input dominates: in the video request,
video_tokensmake up 99.6% of input (21,299 / 21,375); the text instruction is negligible. Video tokens grow with video length and count. - Reasoning counts as output: with reasoning on, 318 of the 369 output tokens (86%) in the text sample are reasoning. Turning reasoning off for simple extraction or classification cuts output substantially.
max_tokensincludes input: ifmax_tokensis smaller than the video's token count, the request is truncated or fails.
7. Cost โ
Vega VL is billed pay-as-you-go by token, under VOD's AIGC Text (large-model text processing) billing item. Each request is metered from the returned usage in three parts: input, cache hits, and output. AIGC Text does not currently support resource-pack deduction.
List prices โ
| Model version | China site input (CNY / 1M tokens) | China site output | China site cache hit | International input (USD / 1M tokens) | International output | International cache hit |
|---|---|---|---|---|---|---|
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 |
- Prices as of 2026-11-15; the official list prices and your console bill are authoritative.
- Output costs about 3.2โ5ร input; cache hits cost 20% of input (Lite / Flash) or about 12% (Pro).
- Reasoning tokens (
reasoning_tokens) are counted incompletion_tokensand billed at the output price.
Estimating cost โ
Cost per call = (prompt_tokens โ cached_tokens) ร input price
+ cached_tokens ร cache-hit price
+ completion_tokens ร output price
(prices are per 1M tokens, so divide the result by 1,000,000)Cost examples โ
Reference values
These figures apply the list prices to the usage from Measured consumption above, to show the order of magnitude. Actual cost varies with material length, prompt, and output length; your bill is authoritative.
Video understanding (input 21,375 / of which video 21,299 / output 73 tokens, no cache):
| Version | China site per call | China site per 1,000 calls | International per call | International per 1,000 calls |
|---|---|---|---|---|
| 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 |
Input accounts for over 98% of the cost โ video length sets the order of magnitude; the few dozen output tokens barely matter.
Repeated questions on the same video, with the video hitting the cache (assuming all 21,299 video tokens hit the cache, everything else unchanged):
| Version | China site per 1,000 calls | International per 1,000 calls | Saving vs. no cache |
|---|---|---|---|
| Lite | ยฅ3.22 | $0.64 | about 79% |
| Flash | ยฅ14.10 | $2.07 | about 78% |
| Pro | ยฅ24.83 | $3.75 | about 86% |
Ways to reduce cost โ
| Approach | Affects | Description |
|---|---|---|
| Use a lower tier | Unit price | For the same video sample, Lite costs about 1/11 of Pro. Use Lite for classification, screening, and frequent calls; reserve Pro for complex tasks |
Fix Tx-User-Session-Id | Cache hits | Send the same session ID when asking repeatedly about the same material; hits are billed at the cache price and show in cached_tokens / cache_read_tokens |
| Ask everything in one request | Input | Combine summary, chapters, and tags for the same video into one instruction instead of re-sending the video |
| Trim the material | Input | Send only the segment you need; video tokens grow with length |
| Turn off reasoning | Output | Leave thinking_enabled off for simple tasks, or set reasoning_effort: "none" / "minimal"; reasoning tokens are billed at the output price |
| Set per-key quotas | Risk control | Set a quota for each key in API Key Management to cap runaway usage |
Bills are under Usage Statistics โ AIGC โ AI Text, or via DescribeAigcUsageData; see Usage lookup.
Error codes โ
| HTTP status | Meaning |
|---|---|
200 | Success |
400 | Invalid request parameters |
401 | Authentication failed (invalid token) |
403 | Insufficient permission or service suspended (e.g. overdue payment) |
404 | Model or endpoint not found (e.g. unsupported model name, wrong path) |
429 | Rate limited |
5xx | Server / upstream error. Sending video with type: "file" returns 502 + 502003 |
Every error response includes a specific message and a request_id, and every response carries an X-Request-Id header for troubleshooting. Error structure:
{
"error": {
"code": "404001",
"message": "model not found: xxx",
"type": "CodeModelNotExist",
"param": null
},
"request_id": "01a0a52a-..."
}| Error code | type | Common cause |
|---|---|---|
401001 | CodeAuthFailed | Invalid key, or a newly created key not yet synced to the gateway (about 1 minute) |
404001 | CodeModelNotExist | Misspelled model name |
502003 | CodeUpstreamError | Upstream parameter error, e.g. video passed the wrong way |
Usage lookup โ
In the console โ
| Scope | Where |
|---|---|
| Whole account | VOD console Usage Statistics โ AIGC โ "AI Text" |
| A specific SubAppId | Application Management (China site: link) โ click the application โ Usage Statistics โ AIGC โ "AI Text" |
| Calls per API key | Call statistics; each key's name appears here |
| Request logs | Request logs |
Via API โ
| Site | API |
|---|---|
| China site | Query AIGC usage statistics |
| International site | DescribeAigcUsageData |
Token management APIs โ
| Action | API | Docs |
|---|---|---|
| Create | CreateAigcApiToken | China site ยท International site |
| Delete | DeleteAigcApiToken | China site ยท International site |
| Describe | DescribeAigcApiTokens | China site ยท International site |
| Update | UpdateAigcApiToken | China site Explorer ยท International site Explorer |