Video understanding

Use a route with video_input. The inline example uses a small MP4 data URL in the object form video_url.url. Public URL handling, audio-track interpretation and duration limits vary by provider; a generated video model is not automatically a video-understanding model.

Run a request

Use Python 3 or Node 22, and export TOKENHUB_API_KEY from your secret store. Download the sample, or replace it with your own file of the same format. Each model request uses your account's paid allowance.

curl --fail "https://aihub.belive.sg/docs/examples/video/kling-3-paper-boat.mp4" -o clip.mp4

python3 - <<'PY'
import base64, json
from pathlib import Path

encoded = base64.b64encode(Path("clip.mp4").read_bytes()).decode("ascii")
body = {
    "model": "qwen/qwen3.8-flash",
    "provider": {"only": ["alibaba-model-studio"]},
    "max_tokens": 4000,
    "messages": [{"role": "user", "content": [
        {"type": "text", "text": "Describe the actions in this clip."},
        {"type": "video_url", "video_url": {"url": "data:video/mp4;base64," + encoded}},
    ]}],
}
Path("request.json").write_text(json.dumps(body))
PY
curl --fail-with-body "https://tokenhub-api.belive.sg/api/v1/chat/completions" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

import base64, json
from pathlib import Path

encoded = base64.b64encode(Path("clip.mp4").read_bytes()).decode("ascii")
body = {
    "model": "qwen/qwen3.8-flash",
    "provider": {"only": ["alibaba-model-studio"]},
    "max_tokens": 4000,
    "messages": [{"role": "user", "content": [
        {"type": "text", "text": "Describe the actions in this clip."},
        {"type": "video_url", "video_url": {"url": "data:video/mp4;base64," + encoded}},
    ]}],
}

import os, urllib.request
request = urllib.request.Request(
    "https://tokenhub-api.belive.sg/api/v1/chat/completions", data=json.dumps(body).encode(),
    headers={"Authorization": "Bearer " + os.environ["TOKENHUB_API_KEY"], "Content-Type": "application/json"},
)
with urllib.request.urlopen(request, timeout=120) as response:
    result = json.load(response)
    print(result["choices"][0]["message"]["content"])
    print(result.get("usage"))
    print(response.headers.get("X-Generation-Id"))

import { readFile } from "node:fs/promises";

const encoded = (await readFile("clip.mp4")).toString("base64");
const apiKey = process.env.TOKENHUB_API_KEY;
if (!apiKey) throw new Error("Set TOKENHUB_API_KEY");
const response = await fetch("https://tokenhub-api.belive.sg/api/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: "Bearer " + apiKey, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "qwen/qwen3.8-flash", provider: { only: ["alibaba-model-studio"] }, max_tokens: 4000,
    messages: [{ role: "user", content: [
      { type: "text", text: "Describe the actions in this clip." },
      {"type": "video_url", "video_url": {"url": "data:video/mp4;base64," + encoded}},
    ] }],
  }),
});
if (!response.ok) throw new Error("HTTP " + response.status + ": " + await response.text());
const result = await response.json();
console.log(result.choices[0].message.content, result.usage);
console.log(response.headers.get("X-Generation-Id"));

The response is a normal Chat Completion: read the assistant content, reported usage and X-Generation-Id.

Uploaded video

For MP4/MOV beyond the inline body limit, reserve and upload a workspace file, then use tokenhub://files/<id> as the object video_url.url. A bare string video_url does not resolve a AI Hub file. Ownership, expiry and the selected route are checked before dispatch.

Asynchronous chat jobs

POST /api/v1/chat/jobs submits a Chat body with video on vertex-global and requires an Idempotency-Key of 1 to 256 characters. It accepts one model, no streaming or fallback models list, and no inline media parts. A new job returns 202; a same-body replay returns 200; a changed body with the same key returns 409.

Use GET /api/v1/chat/jobs/<id> to poll, or the authenticated list route filtered by idempotency_key to reconcile an uncertain submit. POST /api/v1/chat/jobs/<id>/cancel requests cancellation. Read terminal status, result and usage after cancelling; completed answers remain retrievable for 24 hours before expiry cleanup. Jobs have no callback integration. Keep the same key and body after an uncertain submit.

Choose a model and route

Read GET /api/v1/models in your environment. architecture.input_modalities describes a model, while each endpoint's capabilities identifies the serving route: vision for images, audio_input, video_input or file_input. Check the Models page for available routes. The examples pin a declared route; use a different eligible route only with its own supported request form.

Limits, cost and failures

Base64 increases the request size. The synchronous chat body limit defaults to 20 MiB, and provider format, duration, page and context limits also apply. Keep inline samples small; an uploaded video uses a different path described below. A model's context limit is not a universal media-size limit.

Media input can contribute input tokens or a modality-specific meter. Read the selected route's price table and the resulting usage; do not estimate solely from text length. Key caps and model restrictions still apply.

Malformed input can return 400, an oversized body 413, and an unsuitable route 400 or a routing refusal. See Errors before retrying; after a timeout, reconcile before resubmitting.

Support and limits

Each protocol has its own media block: URL and data inputs and uploaded file IDs have their own schemas and size limits, and a model's page lists its input modalities. PDFs, audio and video are refused on routes that do not take them.

Gateway validation, defaults and response forms are in the operation index and the OpenAPI schemas.

Error codes and recovery are in Errors and recovery. Keep the request or job ID from each response: it identifies the call in Activity and for support.