API 参考

所有接口的详细说明，包含请求参数、示例代码和响应格式。

Base URL

所有请求的基础地址

https://api.rolltok.com

认证方式

除 GET /v1/models 外，所有 API 请求需要在 Header 中携带 API Key 进行认证，支持以下两种方式（任选其一）：

方式一 · Authorization Header（OpenAI 风格）

Authorization: Bearer <your-api-key>

方式二 · x-api-key Header（Anthropic 风格）

x-api-key: <your-api-key>

API Key 可在控制台的「API Keys」页面创建和管理。

GET /v1/models

返回当前平台可用的模型清单，与 OpenAI GET /v1/models 响应格式一致。该接口无需认证，可直接调用。

请求示例

bash

curl https://api.rolltok.com/v1/models

响应示例 200 OK

json

{
  "object": "list",
  "data": [
    {
      "id": "qwen3.8-max",
      "object": "model",
      "created": 1687882411,
      "owned_by": "rolltok"
    },
    {
      "id": "deepseek-v4-pro",
      "object": "model",
      "created": 1687882411,
      "owned_by": "rolltok"
    }
  ]
}

各模型定价见模型列表。

POST /v1/chat/completions

文本对话接口，与 OpenAI Chat Completions API 完全兼容。支持流式和非流式两种响应模式。

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，如 qwen3.7-plus
`messages`	array	是	对话消息列表
`stream`	boolean	否	是否流式输出，默认 false
`temperature`	float	否	采样温度，0-2，默认 1
`max_tokens`	int	否	最大输出 token 数

请求示例

bash

curl -X POST https://api.rolltok.com/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-plus",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手。"},
      {"role": "user", "content": "什么是人工智能？"}
    ],
    "temperature": 0.7
  }'

响应示例

json

{
  "id": "chatcmpl-xxxxx",
  "model": "qwen3.7-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "人工智能是..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 120,
    "total_tokens": 138
  }
}

POST /v1/messages

Anthropic Messages 兼容接口，请求与响应字段对齐 Anthropic Messages API，可直接配合 Anthropic SDK 使用。支持流式与非流式。

必需请求头

anthropic-version: 2023-06-01
缺少该请求头将返回 400 错误（缺少 anthropic-version 请求头）。认证使用 Authorization: Bearer <key> 或 x-api-key: <key>。

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，如 kimi-k3
`messages`	array	是	对话消息列表，必须是非空数组，role 为 user / assistant
`max_tokens`	int	否	最大输出 token 数
`system`	string \| array	否	系统提示，字符串或 text 块数组
`temperature`	float	否	采样温度
`top_p`	float	否	核采样概率
`stop_sequences`	array	否	停止序列
`stream`	boolean	否	是否流式输出，默认 false

请求示例

bash

curl -X POST https://api.rolltok.com/v1/messages \
  -H "x-api-key: <your-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "max_tokens": 1024,
    "system": "你是一个有帮助的助手。",
    "messages": [
      {"role": "user", "content": "什么是人工智能？"}
    ]
  }'

响应示例

json

{
  "id": "msg_xxxxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "人工智能是..."
    }
  ],
  "model": "kimi-k3",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "output_tokens": 120,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

POST /v1/embeddings

向量嵌入接口，与 OpenAI Embeddings API 完全兼容。将文本转换为向量表示，适用于 RAG、语义搜索、聚类分析等场景。

请求参数

参数	类型	必填	说明
`model`	string	是	模型名，如 text-embedding-v3
`input`	string \| array	是	要编码的文本，可以是字符串或字符串数组
`encoding_format`	string	否	编码格式，float（默认）或 base64

请求示例

bash

curl -X POST https://api.rolltok.com/v1/embeddings \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v3",
    "input": "要编码的文本内容"
  }'

响应示例

json

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.001, -0.002, ...]
    }
  ],
  "model": "text-embedding-v3",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

💡 计费说明

Embedding 按输入 tokens 计费，无输出费用。价格详见模型列表。

POST /v1/videos/generations

提交视频生成任务（文生视频）。异步接口：提交成功后立即返回任务 id（task_id），视频结果不同步返回，需调用下方查询接口轮询任务状态获取视频 URL。

支持模型

wanx2.1-t2v-turbo（5 秒 · 720p）、wanx2.1-t2v-plus（5 秒 · 1080p）。参数组合需与模型支持集匹配，未配置定价的组合返回 404。

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，见上方「支持模型」
`prompt`	string	是	视频描述文本，最长 2000 字符
`duration`	int	否	视频时长（秒），可选 5 / 10 / 15，默认 5
`resolution`	string	否	分辨率，可选 480p / 720p / 1080p，默认 720p
`aspect_ratio`	string	否	宽高比，可选 16:9 / 9:16 / 1:1 / 4:3 / 3:4

请求示例

bash

curl -X POST https://api.rolltok.com/v1/videos/generations \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wanx2.1-t2v-turbo",
    "prompt": "一只猫在月光下奔跑",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

响应示例 202 Accepted

json

{
  "id": "vg_1791093600000_k3j9x2",
  "model": "wanx2.1-t2v-turbo",
  "status": "processing",
  "created_at": "2026-10-04T06:00:00.000Z"
}

💡 异步与计费说明

提交时冻结预估费用，任务完成（completed）时按预估费用结算；失败或取消的任务自动解冻、不计费。任务默认超时 10 分钟，超时标记为 failed（error.code = timeout）。生成通常需要数分钟，建议轮询间隔不低于 15 秒（服务端对上游轮询有 15 秒防抖，间隔内的查询返回缓存状态）。价格详见模型列表。

GET /v1/videos/generations/:taskId

查询视频生成任务状态。taskId 为提交接口返回的 id。

请求示例

bash

curl https://api.rolltok.com/v1/videos/generations/vg_1791093600000_k3j9x2 \
  -H "Authorization: Bearer <your-api-key>"

响应字段

字段	类型	说明
`id`	string	任务 ID
`model`	string	模型名称
`status`	string	任务状态：processing（生成中）/ completed（完成）/ failed（失败）/ cancelled（已取消）
`progress`	int	生成进度，0-100
`created_at`	string	创建时间（ISO 8601）
`completed_at`	string \| null	完成时间（ISO 8601），未完成为 null
`video_url`	string	仅 completed 时返回：视频文件下载地址，建议尽快下载转存
`usage`	object	仅 completed 时返回：`{ "total_cost": 结算金额 }`
`error`	object	仅 failed 时返回：`{ "message": 错误描述, "code": 错误码 }`

响应示例（生成中）200 OK

json

{
  "id": "vg_1791093600000_k3j9x2",
  "model": "wanx2.1-t2v-turbo",
  "status": "processing",
  "progress": 40,
  "created_at": "2026-10-04T06:00:00.000Z",
  "completed_at": null
}

响应示例（完成）200 OK

json

{
  "id": "vg_1791093600000_k3j9x2",
  "model": "wanx2.1-t2v-turbo",
  "status": "completed",
  "progress": 100,
  "created_at": "2026-10-04T06:00:00.000Z",
  "completed_at": "2026-10-04T06:03:20.000Z",
  "video_url": "https://cdn.example.com/videos/vg_1791093600000_k3j9x2.mp4",
  "usage": {
    "total_cost": 0.5
  }
}

错误响应

错误响应体统一为 { "code": 错误码, "message": 错误描述, "data": null }。常见错误：400 参数校验失败、401 API Key 缺失或无效、402 当月额度不足、403 无权访问该任务、404 任务不存在或模型未配置价格、429 调用过于频繁（默认 30 次/分钟）、502 上游渠道不可用、503 该模型暂无可用视频渠道。详见错误码。