把模型接入
你的产品。

快速开始

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

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

认证与模型列表

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

Authorization: Bearer $TOKVI_API_KEY

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

选择正确的分组

调用下方图片与万相视频模型时，创建密钥请选择标注为 7.50–7.80折 的图片视频分组。国内站未开放 Auto 自动选择，请明确选择有权限的分组。H3 使用独立分组；文本分组或 H3 分组的密钥不会自动获得上述图片、万相视频模型权限。模型 ID 须与示例保持一致。

查询当前密钥可用的模型

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

使用返回列表中的模型 ID 发起请求，并核对模型广场显示的可用分组及密钥限制。目录展示不等于当前分组可调用。文本示例中的 qwen3.8-flash 需选择支持该模型的文本分组；MiniMax-H3 需选择对应的 H3 分组。不同分组的同名模型可能有不同价格，扣费以实际分组及模型规则为准。

文本模型

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

curl https://tokvi.net/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 事件处理响应。

切换千问、DeepSeek、GLM、Kimi 等国内模型时，请使用模型广场列出的准确 ID，并核对该模型支持的接口、上下文、图像输入和工具参数。图像生成与视频任务不使用上面的文本示例。流式输出仅适用于支持该能力的文本模型，请按 SSE 事件读取响应。

图片生成与编辑

以下图片模型已在国内站接入。不同型号使用不同 API，请选择对应示例。

千问：文生图

示例生成一张 1024 × 1024 图片。成功后从 data[0].url 读取图片链接。

curl https://tokvi.net/v1/images/generations \
  -H "Authorization: Bearer $TOKVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen-image-2.0-pro",
  "prompt": "A red ceramic cup on a wooden table, soft daylight.",
  "n": 1,
  "size": "1024x1024"
}'

千问：参考图片编辑

将示例链接替换为你自己的可访问 HTTPS 图片。通过 input.messages 扩展字段传入参考图，仍须提供 prompt。使用 SDK 时可通过额外请求体传入该扩展。

curl https://tokvi.net/v1/images/generations \
  -H "Authorization: Bearer $TOKVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen-image-2.0-pro",
  "prompt": "Change the cup to blue, keep the rest unchanged.",
  "n": 1,
  "size": "1024x1024",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "image": "https://your-public-host.example/reference.png"
          },
          {
            "text": "Change the cup to blue, keep the rest unchanged."
          }
        ]
      }
    ]
  }
}'

万相：提交后台图片任务

将 wan2.7-image 替换为 wan2.7-image-pro 即可选择专业版。下方 size 使用星号分隔尺寸。

curl https://tokvi.net/v1/responses \
  -H "Authorization: Bearer $TOKVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan2.7-image",
  "input": "A small green ceramic vase, still life, soft daylight.",
  "n": 1,
  "size": "1024*1024",
  "background": true
}'

保存返回的 id（例如 resp_xxx），继续通过 Responses API 查询：

curl https://tokvi.net/v1/responses/resp_xxx \
  -H "Authorization: Bearer $TOKVI_API_KEY"

等待 status 变为 completed。图片链接以 Markdown 形式出现在 output[].content[].text，对应内容类型为 output_text。如果状态为 failed，查看错误及任务记录。Responses ID 与原生任务 ID 不能混用。

万相视频 API

wan3.0-video 和 wan3.0-video-prime 支持异步视频生成，分辨率支持 480P、720P 和 1080P。下方示例固定生成 2 秒、480P 视频，实际等待时间取决于型号和队列。

每次 POST 都可能产生新的计费任务。请保存 ID 并查询同一任务；请求超时后先核对原任务是否创建，不要自动重复提交。

1. 提交文生视频

curl https://tokvi.net/v1/videos \
  -H "Authorization: Bearer $TOKVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan3.0-video-prime",
  "prompt": "A quiet mountain valley at sunrise, slow clouds, still camera.",
  "seconds": 2,
  "resolution": "480P",
  "ratio": "16:9",
  "audio": false
}'

图生视频

使用同一接口传入可访问的 HTTPS 图片链接即可生成动态视频。运行前请替换占位链接：

curl https://tokvi.net/v1/videos \
  -H "Authorization: Bearer $TOKVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan3.0-video-prime",
  "prompt": "The camera gently moves closer to the cup.",
  "image": "https://your-public-host.example/reference.png",
  "seconds": 2,
  "resolution": "480P",
  "audio": false
}'

2. 查询视频任务

保存提交响应中的 id，替换下方 task_xxx。状态包括 queued、in_progress、completed 和 failed。每次查询间隔数秒。

curl https://tokvi.net/v1/videos/task_xxx \
  -H "Authorization: Bearer $TOKVI_API_KEY"

3. 下载已完成的视频

任务变为 completed 后，用同一密钥请求视频内容。状态接口返回任务信息，不直接返回视频文件。

curl https://tokvi.net/v1/videos/task_xxx/content \
  -H "Authorization: Bearer $TOKVI_API_KEY" \
  --output tokvi-video.mp4

内容接口返回视频字节，使用保存的 MP4 前请确认 HTTP 状态成功。任务失败时应查看错误及任务记录，而非继续下载。

万相 3.0 按分辨率及可计费的输入视频、输出视频合计秒数计费。上述示例不包含参考视频；其他素材组合、较长时长和音频选项各有型号限制，调整前请查看模型说明及错误响应。

MiniMax-H3 视频生成

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

1. 提交任务

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

curl https://tokvi.net/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.net/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 分别计费，图片按张、视频按可计费秒数或任务使用量计费。API 请求中的 size、seconds 等参数仍表示尺寸和用量，不是金额。

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

支付方式、充值及活动以控制台的实际开放状态为准。海外站的美元余额、兑换码与订单不适用于国内站。折扣以对应模型的官方参考价与人民币客户价比较，具体金额以实际分组的模型价格和消费账单为准。

排查问题

• 认证失败：检查请求头格式、密钥有效期，以及密钥是否来自 tokvi.net。
• 模型不可用或权限不足：核对模型 ID、密钥模型限制与所选分组。
• 结果字段不符：千问 Images 读取 data[].url；万相 Responses 读取 output[].content[].text；万相 Videos 通过 /v1/videos/{id}/content 下载；H3 读取 task.content.url。
• HTTP 503 或空响应：保留请求 ID 与响应 Content-Type，核对模型可用性并联系支持；已受理的任务不要据此重复提交。
• 参数错误：根据响应的错误信息修改请求，不同模型不一定支持相同参数。
• 额度不足：查看账户余额、密钥额度及尚未结算的异步任务。
• HTTP 429：请求受到限流；如响应包含 Retry-After，按该值等待，并降低并发和查询频率。
• 视频没有立即返回：保存提交得到的任务 ID，继续查询状态，不要反复创建新任务。

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