TOKVI GLOBAL / DEVELOPER DOCS

把模型接入
你的产品。

通过 Tokvi 国际站接入国内与国际模型。这份指南使用 https://tokvi.ai，覆盖密钥认证、文本请求与 MiniMax-H3 视频任务。

进入控制台 ↗查看模型与计费

快速开始

在 Tokvi 国际站注册并完成邮箱验证，或使用已有国际站账户登录。
在控制台的“API 密钥”页面创建密钥，确认所选分组、模型权限、额度和有效期。
在服务端设置 TOKVI_API_KEY 环境变量，使用下方示例调用模型。
在使用日志中查看请求结果与费用。

国际站与国内站的账户、API 密钥、余额和使用记录独立。国际站账户额度与模型价格以美元 USD 展示；请勿混用国内站的密钥或接口地址。

使用要求填写 Base URL 的 OpenAI 兼容客户端时，填入 https://tokvi.ai/v1。直接使用 curl 时填写完整接口路径，避免重复添加 /v1。

认证与模型列表

模型调用接口使用 API 密钥进行 Bearer 认证：

Authorization: Bearer $TOKVI_API_KEY

密钥仅保存在服务端，不要放入公开网页、代码仓库或日志。若需要更换密钥，请在控制台创建新密钥，并禁用不再使用的旧密钥。

查询当前密钥可用的模型

curl https://tokvi.ai/v1/models \
  -H "Authorization: Bearer $TOKVI_API_KEY"

使用返回列表中的模型 ID 发起请求。模型广场展示的平台目录可能大于某一把密钥的可调用范围。

文本模型

支持 OpenAI 兼容协议的文本模型可通过 POST /v1/chat/completions 调用。以下示例使用国际站已上架的 qwen3.8-flash；调用前仍需确认该密钥具有对应权限和可用额度。

curl https://tokvi.ai/v1/chat/completions \
  -H "Authorization: Bearer $TOKVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-flash",
    "messages": [
      {"role": "user", "content": "你好，Tokvi"}
    ]
  }'

非流式响应中的文本通常位于 choices[0].message.content。需要流式输出时，可对支持的模型设置 "stream": true，并按 SSE 事件处理响应。

切换 GPT、Claude、DeepSeek 等模型时，请使用模型广场列出的准确 ID，并核对该模型支持的接口、上下文、图像输入和工具参数。图像生成与视频任务不使用上面的文本示例。

MiniMax-H3 视频生成

MiniMax-H3 使用异步任务：先提交生成请求，再查询状态，完成后获取视频地址。也可以直接打开视频工作台，或阅读 MiniMax-H3 API 专页。

1. 提交任务

每次提交都可能创建新的付费任务。若网络中断、超时或未收到响应，请先在控制台核对任务记录，不要自动重复提交。客户端提供的幂等键不能保证重复请求去重。

curl https://tokvi.ai/v2/video_generation \
  -H "Authorization: Bearer $TOKVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "A misty mountain valley at dawn"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }'

保存成功响应中的 task_id，后续查询必须使用这个公开任务 ID。提交成功表示任务已受理，不代表视频已经生成。

2. 查询任务

将下面的 task_xxx 替换为提交响应中的 task_id：

curl https://tokvi.ai/v2/query/video_generation/task_xxx \
  -H "Authorization: Bearer $TOKVI_API_KEY"

状态包括 queued、running、succeeded 和 failed。提交响应使用顶层 status；查询响应通常在 task.status 中返回状态。首次查询可能只有任务标识，尚未取得状态时应继续等待。

成功：从 task.content.url 获取视频文件地址。
失败：查看 task.error.message 和 task.error.code，并在控制台核对任务记录。
排队或执行中：间隔数秒后查询，遇到限流时按提示延长间隔。

输入与计量

当前接入提供 768P 文生视频、图生视频和参考生视频。不同输入方式对素材和参数有各自限制，参考视频与首尾帧不能混在同一个请求中。本文示例为不带参考素材的 5 秒文生视频任务。

输出视频、输入视频、超额图片与 Context IR 可能分别计量。请在模型广场查看完整计费项，不能仅按输出时长推算所有任务的费用。

计费与额度

国际站按实际用量扣除美元账户额度。模型广场展示客户价格与计费单位；不同模型可能按输入／输出 Token、图片张数、视频时长或任务使用量分别计费。

异步视频任务可能先预占额度，完成后按任务规则结算；失败后的额度释放以任务状态和账单记录为准。发起请求前，请确认账户余额与密钥额度足够。

支付方式、充值及活动以控制台的实际开放状态为准。国内站的人民币额度、兑换码与订单不会自动转移到国际站。

排查问题

认证失败：检查请求头格式、密钥有效期，以及密钥是否来自 tokvi.ai。
模型不可用或权限不足：核对模型 ID、密钥模型限制与所选分组。
参数错误：根据响应的错误信息修改请求，不同模型不一定支持相同参数。
额度不足：查看账户余额、密钥额度及尚未结算的异步任务。
HTTP 429：请求受到限流；如响应包含 Retry-After，按该值等待，并降低并发和查询频率。
视频没有立即返回：保存提交得到的任务 ID，继续查询状态，不要反复创建新任务。

需要排查时，请保留请求时间、模型名称、公开任务 ID 和错误码，不要提供完整 API 密钥或含隐私的输入内容。

把模型接入你的产品。