API 文档

tokgate.io 完整接口文档

统一鉴权与计量，按模型厂家使用对应协议：Anthropic 模型走 Anthropic Messages，Google 模型走 Gemini 原生格式，其余大语言模型走 OpenAI 兼容格式。

从聊天接口开始 → 先看使用指南

概述

tokgate.io 提供 RESTful API，所有 AI 模型能力共用同一个数据面网关与同一套 API Key。你不需要为每家模型厂商单独接入 SDK、单独维护凭据。

API Host https://api.tokgate.io

聊天按厂家分流：Anthropic → Messages，Google → Gemini 原生，其余大语言模型 → OpenAI Chat Completions。三种格式不能任意混用。
图像按厂家原生端点、请求体和参数调用，Gemini、GPT Image、Seedream、Qwen Image 的格式不可混用。
视频通过异步任务接口调用：提交生成任务，保存任务 ID，再轮询状态与产物。

AI 模型接口

聊天

对话补全接口，支持多轮对话、流式输出、工具调用。请求格式由模型厂家决定：OpenAI 兼容、Anthropic Messages或 Gemini 原生。

聊天（Chat）

图像

AI 图像生成与编辑。按厂家原生协议接入 Gemini Image、gpt-image-2、seedream-5-0 与 qwen-image-3.0-pro。

图像（Images）

视频

seedance 与 happyhorse 异步视频生成接口，包含任务提交、状态轮询与产物获取。

视频（Videos）

鉴权

所有接口用 API Key 鉴权，密钥在控制台「API 密钥」页创建，以 sk- 开头。不使用登录 Cookie。

OpenAI 格式

Authorization: Bearer sk-***
Content-Type: application/json

Anthropic 格式

Anthropic 官方 SDK 使用 x-api-key 头并要求版本号。两种写法都受支持，用官方 SDK 时按下面第一种。

x-api-key: sk-***
anthropic-version: 2023-06-01
Content-Type: application/json

# 或沿用 Bearer 写法
Authorization: Bearer sk-***
anthropic-version: 2023-06-01
Content-Type: application/json

Gemini 原生格式

Google 模型使用 Gemini 原生请求结构，并通过 Authorization: Bearer ... 鉴权。

x-goog-api-key: sk-tokgate-你的APIKey
Content-Type: application/json

密钥范围会影响可用模型创建密钥时若设置了模型白名单，白名单外的模型返回 403；设置了消费配额上限，用尽后该密钥返回额度不足，但不影响账户其它密钥。

端点清单

方法	路径	说明
GET	`/v1/models`	查询当前密钥可用的模型列表
POST	`/v1/chat/completions`	对话补全（OpenAI 格式），支持流式与工具调用
POST	`/v1/messages`	Anthropic 模型消息接口（Anthropic 格式）
POST	`/v1beta/models/{model}:generateContent`	Google 模型内容生成（Gemini 原生格式）
POST	`/v1beta/models/{model}:streamGenerateContent`	Google 模型流式内容生成（Gemini 原生格式）
POST	`/v1/images/generations`	图像生成（文生图）
POST	`/v1/images/edits`	GPT Image 图像编辑（图生图 / 局部重绘）
POST	`/api/v3/images/generations`	Seedream 图像生成与编辑
POST	`/api/v1/services/aigc/multimodal-generation/generation`	Qwen Image 图像生成与编辑
POST	`/api/v3/contents/generations/tasks`	提交 seedance 系列视频生成任务
GET	`/api/v3/contents/generations/tasks/{id}`	查询 seedance 任务状态与产物
POST	`/api/v1/services/aigc/video-generation/video-synthesis`	提交 happyhorse 系列视频生成任务
GET	`/api/v1/tasks/{task_id}`	查询 happyhorse 任务状态与产物

视频接口采用异步任务Seedance 与 HappyHorse 提交后都会返回任务 ID。请保存 ID 并轮询对应查询接口，成功后及时下载转存产物。

错误码

网关级错误（如鉴权、配额或路由失败）使用对应 HTTP 状态码，并返回以下扁平 JSON 结构。请求到达模型上游后，也可能返回厂家原生错误体，客户端不应只解析一种结构：

{
  "code": "GW-401",
  "message": "Invalid API key",
  "requestId": "req_xxxxxxxx",
  "timestamp": "2026-08-01T00:00:00Z"
}

请求已到达 Anthropic 上游后，可能返回 Anthropic 风格错误体：

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

请求已到达 Google 上游后，可能返回 Google 风格错误体，常见字段为 error.code、error.message 与 error.status。

状态码	典型 type / code	含义与处理
400	`invalid_request_error`	参数缺失或取值非法。按对应接口的参数表核对，尤其是模型专属参数的取值组合。
401	`invalid_api_key`	密钥无效、被删除、已停用或已过期。检查请求头写法与密钥完整性。
402	`insufficient_quota`	Credits 余额不足，或该密钥的消费配额上限已用尽。到控制台充值 Credits 或调高配额。
403	`permission_denied`	密钥无权调用该模型（模型白名单）或该模型未对当前账户开放。
404	`model_not_found`	模型名称写错或已下线。调 `GET /v1/models` 确认。
429	`rate_limit_exceeded`	超过密钥 RPM 或上游并发上限。指数退避重试，或调高密钥速率限制。
500	`internal_error`	网关内部错误，已自动告警，可安全重试。
503	`upstream_unavailable`	上游暂时不可用，网关会按路由策略自动切换备用提供商；持续失败请稍后重试。

限流与重试

RPM：每把密钥可单独设置每分钟请求上限，留空为不限。可在控制台「API 密钥」页编辑。
消费配额：每把密钥可设累计消费上限（美元），用尽后该密钥自动失效。
重试策略：对 429 与 5xx 使用指数退避（如 1s、2s、4s），并设置最大重试次数，避免雪崩。
超时设置：对话建议开流式改善首字延迟；图像同步返回但耗时较长，客户端超时不要设得过短；视频为异步任务，务必用轮询而非长连接。
幂等：视频任务提交成功后请保存返回的任务 ID 并轮询，不要重复提交，重复提交会重复计费。

下一步

聊天（Chat） —— OpenAI、Anthropic 与 Gemini 三种厂家协议的请求和流式说明。
图像（Images） —— Gemini Image、gpt-image-2、seedream-5-0、qwen-image-3.0-pro 厂家原生接口参考。
视频（Videos） —— seedance 与 happyhorse 异步任务接口，包含提交、轮询与产物获取。