TOKENSTAR DEVELOPER

用一套 Key 接入多模型 API

页面会按当前访问域名自动使用国内或海外 API 根地址，复制文本、图片和视频接口示例。临时 Key 只在当前内存中替换，不会上传或保存。

1获取 API Key

登录后在令牌管理创建 Virtual Key。

2确认环境

地址和复制内容会跟随当前访问域名。

3复制示例

按你的接入场景选择对应接口。

常见问题

错误码、环境变量和客户端配置排查已经移到独立 FAQ 页面。

查看常见问题

环境与鉴权

页面展示与复制内容会按当前访问域名自动使用同一地址。

临时 API Key

仅当前页面内存使用，刷新后清空。

网关根地址https://api.tokenstar.world

OpenAI Base URLhttps://api.tokenstar.world/v1

Claude Base URLhttps://api.tokenstar.world

鉴权规则

所有接口使用平台 API Key。OpenAI 兼容接口使用 Authorization: Bearer ${API_KEY}；Claude / Anthropic 接口使用 x-api-key: ${API_KEY}。

Base URL 规则

OpenAI 兼容客户端通常填写到 /v1；Claude Code 的 ANTHROPIC_BASE_URL 不带 /v1。

TokenStar Agent Skill

把 TokenStar 公开文档压缩成 AI Agent 可直接使用的 SKILL.md，覆盖文本、图片、视频、素材、回调和客户端配置。

Skill 路径tokenstar-codex-gateway/SKILL.md

下载后将文件放入下列目录结构，或复制内容交给你的 Agent/Skill 管理流程。

密钥安全Skill 只包含占位符和环境变量名，不会读取、保存或写入你在页面里输入的临时 API Key。

AGENT SKILL

SKILL.md 预览

文本生成接口

文本生成支持 OpenAI 兼容协议与 Claude / Anthropic 协议，按客户端或业务场景选择。

POST/v1/chat/completionsOpenAI Chat Completions同步

Chat Completions

通过平台 API Key 调用 OpenAI 兼容聊天接口。

鉴权

Authorization: Bearer <API_KEY>
Content-Type: application/json

请求参数

字段	必填	说明
`model`	是	内置模型 ID
`messages`	是	OpenAI 兼容消息数组
`stream`	否	是否以 SSE 风格流式返回
`max_tokens / temperature / top_p`	否	兼容参数透传

Chat Completions

curl -sS "https://api.tokenstar.world/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-plus",
    "messages": [
      {"role": "user", "content": "只回复OK"}
    ]
  }'

响应示例

注意事项

可选 requestId 请求头用于问题排查。

POST/v1/responsesOpenAI Responses同步

Responses API

调用 OpenAI Responses 兼容接口，适用于 Codex 自定义 provider。

鉴权

Authorization: Bearer <API_KEY>
Content-Type: application/json

请求参数

字段	必填	说明
`model`	是	模型 ID
`input`	是	字符串或 Responses 输入项
`stream`	否	是否流式返回

Responses API

curl -sS "https://api.tokenstar.world/v1/responses" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "只回复OK"
  }'

注意事项

Codex 自定义 provider 的 wire_api 使用 responses。

POST/v1/messagesAnthropic Messages同步

Claude Messages

通过 Anthropic Messages 协议调用 Claude 模型。

鉴权

x-api-key: <API_KEY>
anthropic-version: 2023-06-01

请求参数

字段	必填	说明
`model`	是	Claude 模型 ID
`max_tokens`	是	最大生成长度
`messages`	是	Anthropic 消息数组

Messages 调用形态

注意事项

Claude Code 的 ANTHROPIC_BASE_URL 使用根地址，不带 /v1。

可用模型

完整模型列表、上下文长度和输入能力请查看模型广场。模型广场

图片生成接口

图片接口通常同步返回，请按不同模型响应字段读取图片内容。

gpt-image

POST /v1/images/generations · POST /v1/images/edits

响应位置: data[].b64_json

适用模型：gpt-image-2。
图片生成使用 JSON 请求；图片编辑和局部重绘使用 multipart/form-data 上传 image，可选上传 mask。
常用尺寸包含 1024x1024、2048x2048；输出格式按模型支持范围传入。

图片生成

图片编辑

蒙版局部重绘

Gemini 兼容图片模型

POST /v1beta/models/{model}:generateContent

响应位置: candidates[].content.parts[].inlineData

适用模型：gemini-3-pro-image-preview、gemini-3.1-flash-image-preview、gemini-2.5-flash-image。
parts 中可能同时包含文本和图片，请遍历 parts 查找 inlineData。

Gemini 兼容图片调用示例

视频生成接口

异步任务、素材与回调的接入信息。

Seedance 视频生成

Seedance 任务创建后通过任务 ID 轮询终态，也可以传 callback_url 接收状态变化。

无参考人视频生成POST /v1/video/generations · GET /v1/video/generations/{task_id}

结果: result_url

无参考人入口使用 seedance-2.0 或 seedance-2.0-fast。
创建任务后保存返回的 id 或 task_id，再用查询接口轮询结果。

创建无参考人任务

查询视频任务

素材组、素材上传与参考人视频生成

POST /volc/asset/CreateAssetGroup · POST /volc/asset/ListAssetGroups · POST /volc/asset/CreateAsset · POST /volc/asset/GetAsset · POST /v1/video/generations

结果: asset://<Id> · result_url

参考人入口使用 seedance-2.0-asset 或 seedance-2.0-asset-fast。
素材支持图片、视频和音频；CreateAsset 仅通过公共可访问 URL 传入素材，不接受内嵌编码或表单文件。
CreateAsset 使用 AssetType、GroupId、Name 和 URL。
创建素材后保存返回的 Id，并使用 GetAsset 按 Id 查询素材；不要依赖名称反查素材。
视频生成请求在 content 中用 asset://<Id> 引用素材。
引用素材生成视频时，content 必须严格按 text、image_url、video_url、audio_url 的顺序传入；请勿调整顺序，否则可能导致报错。

创建素材组

查询素材组

上传素材（URL）

按 ID 查询素材

引用素材创建视频任务

查询参考人视频任务

Kling 视频生成

Kling 新视频接口按路径区分文生、图生、Omni 视频编辑和动作控制；创建返回 data.task_id，按对应 GET 路径轮询 submitted / processing / succeed / failed，成功结果位于 data.task_result.videos[].url。

文本生成视频POST /v1/videos/text2video · GET /v1/videos/text2video/{task_id}

结果: data.task_result.videos[].url

适用模型：kling-v2-6、kling-v3。
创建结果为 data.task_id；查询任务时使用 GET /v1/videos/text2video/{task_id}。
使用字段 model_name、prompt、duration、mode、aspect_ratio、sound；巡检当前使用 mode=std。
如需主体一致性，不建议走文生视频，建议使用 image2video、omni-video 或 motion-control 的 element_list。
保存 request_id 便于排障；成功响应还可能返回 videos[].duration 和 final_unit_deduction。

Kling 文生视频

Kling 查询任务

图片生成视频与主体一致性POST /v1/videos/image2video · GET /v1/videos/image2video/{task_id}

结果: data.task_result.videos[].url

适用模型：kling-v2-6、kling-v3。
图片字段使用顶层 image，不是 image_url，也不是旧版 Image.Url。
image2video 不支持 aspect_ratio，携带会返回 UnknownParameter。
需要主体一致性时传 element_list，并使用 /v1/general/advanced-custom-elements 返回的 subj_... 作为 element_id。
新视频接口禁止使用旧 /aigc/element 返回的 elem_...；混用会返回 invalid_subject_id。
图片 URL 必须是服务端可直接下载的公网 HTTPS 地址。

图生视频基础

图生视频携带主体

图生视频查询任务

Omni 视频编辑POST /v1/videos/omni-video · GET /v1/videos/omni-video/{task_id}

结果: data.task_result.videos[].url

适用模型：kling-v3-omni。
视频编辑使用 video_list，video_list[].video_url 必须是可下载的视频地址。
需要主体一致性时传 element_list，element_id 必须是新主体接口返回的 subj_...。
巡检当前覆盖 kling-v3-omni + std + element_list。
Omni 任务通常耗时更长，不要因 processing 持续时间较长而重复创建。

Omni 视频编辑基础

Omni 视频编辑携带主体

Omni 查询任务

动作控制POST /v1/videos/motion-control · GET /v1/videos/motion-control/{task_id}

结果: data.task_result.videos[].url

基础动作控制适用 kling-v2-6、kling-v3；主体一致性动作控制适用 kling-v3。
必须同时传 image_url 和 video_url；video_url 是动作参考视频，image_url 是主体图片。
必须传 prompt 和 character_orientation；kling-v3 + element_list 时 character_orientation 使用 video。
不要传 duration 或 StaticMask，否则可能返回 UnknownParameter 或任务失败。
kling-v2-6 + element_list 已确认不支持，会返回 subject reference is not supported for model 'kling-v2-6'。

动作控制基础

动作控制携带主体

动作控制查询任务

主体管理POST /v1/general/advanced-custom-elements · GET /v1/general/advanced-custom-elements/{task_id}

结果: data.task_result.elements[].element_id

创建主体是异步任务：保存创建响应的 data.task_id，再用单项查询接口轮询 submitted / processing / succeed / failed。
task_id 用于查询创建任务；查询成功后返回的 element_id 仅用于视频 element_list，二者不能混用。
element_name 与 element_description 必填，分别不超过 20 和 100 个字符；reference_type 使用 image_refer 或 video_refer。
图片主体需要 1 张正面图和 1～3 张其他参考图；当前 Console 仅支持可访问 URL，图片需符合官网格式、大小、尺寸和宽高比限制。
视频主体使用 element_video_list，支持 1 段 MP4/MOV、3～8 秒、1080P、16:9 或 9:16、最大 200MB 的视频。
只有 data.task_status=succeed、元素 status=succeed 且 element_id 非空时，才能将 subj_... 用于视频任务。
按环境、主体素材和接口版本缓存 subj_...；短暂查询失败时不要立即重复创建。
旧 /aigc/element 返回的 elem_... 仅供旧版 /v1/video/generations 使用。
主体查询需同时检查 data.task_status、elements[].status 和非空 elements[].element_id。

创建主体元素

查询主体元素

旧版 Kling 接口入口GET /doc/kling-legacy

结果: 旧版 /v1/video/generations 与 X-TC-Action 文档

旧版页面仅用于存量接口、迁移和历史排障。
新接入请优先使用本模块的 /v1/videos/{endpoint} 新接口。

查看旧版 Kling 接口

任务状态、查询与回调

视频任务必须按异步任务处理；仅在对应接口明确支持 callback_url 时传回调地址，否则按任务查询接口轮询。

异步任务生命周期submitted / queued / NOT_START → running / IN_PROGRESS → succeeded / SUCCESS / DONE / failed / FAILURE / FAIL

结果: Seedance: result_url；Kling 新接口: data.task_result.videos[].url

建议轮询间隔 5 到 10 秒；Kling 新接口按最新文档建议每 10 到 30 秒查询一次，进入终态后停止轮询。
Kling 新接口状态按 submitted / processing / succeed / failed 处理，并在 task_status=succeed 后读取视频 URL。
生成结果 URL 可能包含有效期，成功后应及时下载或转存。
保存 request_id 和 task_id，便于网关及上游问题排查。
callback_url 仅在对应视频接口明确支持时使用；Kling 新视频接口暂不对外提供或不建议依赖 callback_url、watermark_info、external_task_id。
客户回调需返回 HTTP 2xx，并按任务 ID 幂等处理。

submitted→processing→succeed / failed

创建任务后保存 id、task_id 或 Kling Response.JobId，通过查询接口轮询；客户回调需按任务 ID 幂等处理。

第三方 Agent 工具配置

根据 Agent 工具使用不同协议和 Base URL。

Claude Code

Claude Code 环境变量

export ANTHROPIC_API_KEY="${API_KEY}"
export ANTHROPIC_BASE_URL="https://api.tokenstar.world"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_MODEL="claude-sonnet-4-6-thinking"
claude

不要同时设置 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN。

Codex

~/.codex/config.toml

model = "gpt-5.4"
model_provider = "tokenstar"

[model_providers.tokenstar]
name = "TokenStar Gateway"
base_url = "https://api.tokenstar.world/v1"
wire_api = "responses"
env_key = "TOKENSTAR_API_KEY"

启动 Codex

OpenClaw

~/.openclaw/openclaw.json

{
  env: { TOKENSTAR_API_KEY: "${API_KEY}" },
  models: {
    mode: "merge",
    providers: {
      tokenstar: {
        baseUrl: "https://api.tokenstar.world/v1",
        apiKey: "${TOKENSTAR_API_KEY}",
        api: "openai-completions",
        authHeader: true,
        models: [{
          id: "qwen3.7-plus",
          name: "Qwen 3.7 Plus",
          reasoning: true,
          input: ["text", "image"],
          contextWindow: 200000,
          maxTokens: 32768
        }]
      }
    }
  }
}

Anthropic provider 的 Base URL 使用根地址。

把文档交给 AI Agent

下载同源的 SKILL.md，让 AI Agent 直接读取 TokenStar API、Base URL、模型、媒体任务和排障规则，减少人工翻文档。