TokenStack AI 接入文档

快速接入 GPT、Claude、Gemini 等主流 AI 模型，无需信用卡，国内直连。本文档将带你从注册到配置完成，全程图文引导。

新手首选 ⚡ 要配置 AI 客户端？用 CC Switch 一键导入 粘贴密钥 → 选工具 → 点导入，30 秒完成，全程零手动填写
立即开始 →
推荐返利 💰 推荐好友用 TokenStack，赚持续返利 朋友每消费一笔，你都有返利 · 看板随时查数据 · 一键申请提现
了解详情 →
入门指南 2 篇

注册账号、创建令牌，两步开始使用
智能体配置 12 篇

⚡ CC Switch 一键导入 30 秒完成配置；Claude Code、Codex、Cursor、ChatBox 等主流客户端接入方法
API 参考 3 篇

GPT Image 2 图片、NanoBanana 图片、视频生成（统一格式，11 个档位一套接口）
帮助 2 篇

注意事项、获取一对一技术支持

💰 推荐返利计划

把 TokenStack 推荐给朋友，朋友注册后每消费一笔，你都能拿持续返利。返利按好友的实际消费额计算，每月人工对账后微信打款。

怎么赚？三步开始

1

打开推广看板，拿你的链接和海报

登录你的 TokenStack 账号后，点本页下方的「查看我的推广数据」打开你的专属看板（自动认出是你）。里面直接给你两样东西：

  • 专属邀请链接——一键复制，发给任何人
  • 推广海报（带二维码 + 宣传语，3 种样式可选）——一键下载，直接发朋友圈 / 社群

不用再去后台翻邀请码。别人通过你的链接、或扫你海报上的二维码注册，系统会永久记住是你邀请的。

2

把链接 / 海报发出去

链接或海报，发给朋友、发到技术社群、写进你的 AI 教程 / 公众号 / 视频简介。谁最适合推？有开发者人脉、做 AI 内容、运营技术社群的人——你的受众越是真在用 AI，转化越高、返利越多。

3

朋友消费，你拿返利

朋友通过你的链接 / 海报注册、充值、调用模型，按他们的实际消费额给你返利。下线消费在看板里随时能查（脱敏），想结算时在看板点「申请提现」填支付宝，每月人工对账后打款。具体返利比例加微信详谈（关系型长期合作，量大比例可谈）。

📊 查看我的推广数据 →

登录你的 TokenStack 账号后打开即可，自动认出是你——无需令牌、无需找客服。能看到：邀请了多少人、下线近 3 个月的消费。
数据仅你本人登录可见，别人看不到。

对账与规则

  • 怎么领返利：每月人工对账，加微信（下方「获取帮助」二维码）确认你的下线消费额后打款到你指定方式。
  • 返利按「消费额」算：不是按充值额，是按好友实际用掉的金额。朋友充了不用，不产生返利；用得越多，你返得越多。
  • 数据看板定期更新：看板里的下线消费是定期刷新的快照（不是实时），脱敏显示，只保留近 3 个月。
⚠️ 红线（违反取消返利资格）：
  • 自己邀请自己、注册小号刷返利 —— 无效，发现直接取消资格并封号
  • 虚假宣传、冒充官方 —— 取消合作
  • 最终解释权归 TokenStack

注册与登录

使用 TokenStack 的第一步是创建账号。

1

访问官网

打开浏览器，访问 www.tokenstack.cc，点击页面右上角的「注册」按钮。

2

填写注册信息

输入用户名、密码完成注册。注册成功后会自动登录到管理后台。

注册页面

创建令牌（Token）

令牌就是你的 API 密钥，用来验证你的身份。每次调用 AI 模型时都需要带上它。

1

进入令牌管理

登录后台后，在左侧菜单找到「令牌」，点击进入令牌管理页面。

2

新建令牌

点击「添加令牌」按钮，填写令牌名称（方便你自己区分用途，比如"Cursor 用"、"Claude Code 用"）。

3

复制并保存

创建成功后，系统会显示一个以 sk- 开头的密钥。请立即复制保存，关闭后将无法再次查看完整密钥。

令牌创建页面 令牌列表
提示：建议为不同的工具创建不同的令牌，方便管理和追踪用量。如果某个令牌泄露了，只需要删除那一个，不影响其他工具。

智能体配置

选择你使用的 AI 工具，按照教程配置即可开始使用 TokenStack 的模型服务。

💡 命令运行报错？下面教程里的命令已按操作系统分开（macOS / Linux 和 Windows 各一份，页面会自动选中你的系统）。如果照着做还是报错，把报错信息和这一节的教程内容一起复制给任意 AI 助手（豆包、ChatGPT、Claude 都行），告诉它你的操作系统，它会给你能直接用的命令。

手动配置

如果不使用 Skill 或 CC Switch，也可以按照以下指南手动配置各客户端。

API 端点信息

TokenStack 支持三个系列的 API，根据您使用的模型选择对应的 Base URL：

模型系列 Base URL API 类型
Claude https://www.tokenstack.cc anthropic-messages
OpenAI https://www.tokenstack.cc/v1 openai-completions
Google https://www.tokenstack.cc/v1 google-generative-ai

OpenClaw（龙虾）

OpenClaw 是一款开源的 AI 编程 CLI 工具，通过 JSON5 配置文件管理模型和 Provider。

配置文件位置

配置文件路径：~/.openclaw/openclaw.json（JSON5 格式，支持注释）

第一步：添加 Provider

打开配置文件，在 models.providers 中添加 TokenStack。以下以 Claude 系列为例：

openclaw.json 
{
  models: {
    mode: "merge",
    providers: {
      tokenstack: {
        baseUrl: "https://www.tokenstack.cc",
        apiKey: "sk-你的密钥",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
          { id: "claude-opus-4-6", name: "Claude Opus 4.6" }
        ]
      }
    }
  }
}

第二步：设置默认模型（可选）

如果你希望 OpenClaw 默认使用 TokenStack 的模型，可以添加以下配置：

openclaw.json 
{
  agents: {
    defaults: {
      model: {
        primary: "tokenstack/claude-sonnet-4-6"
      }
    }
  }
}

第三步：验证配置

保存配置文件后，在终端运行 OpenClaw，发送一条消息测试是否正常响应。如果看到模型回复，说明配置成功。

🖼️
截图待补充：OpenClaw 配置成功后的对话界面
注意：OpenClaw 使用 Anthropic Messages API，Base URL 为 https://www.tokenstack.cc，不带 /v1。如果你要使用 OpenAI 系列模型，需要将 api 改为 "openai-completions"，baseUrl 改为 https://www.tokenstack.cc/v1。

Hermes Agent（爱马仕）

Hermes Agent 是 Nous Research 开源的 AI 编程 Agent，俗称「爱马仕」，被业内称为 OpenClaw 的热门平替（GitHub 4.8 万+ 星）。通过修改 ~/.hermes/config.yaml 接入 TokenStack。

第一步：编辑配置文件

打开（或新建）~/.hermes/config.yaml（Windows 路径是 C:\Users\你的用户名\.hermes\config.yaml），写入以下内容：

~/.hermes/config.yaml 
model:
  provider: custom
  base_url: "https://www.tokenstack.cc"
  api_key: "sk-你的TokenStack密钥"
  api_mode: "anthropic_messages"
  default: "claude-sonnet-4-6"
  context_length: 200000

第二步：（可选）把 API Key 放到 .env 更安全

不想把密钥明文写进 yaml 的话，把 api_key 这一行删掉，改成在 ~/.hermes/.env 里写：

~/.hermes/.env 
ANTHROPIC_API_KEY=sk-你的TokenStack密钥

第三步：验证并启动

在终端运行：

终端 
hermes config check    # 检查配置完整性
hermes                 # 启动 Agent
🖼️
截图待补充：Hermes Agent 启动后的对话界面
注意：Hermes 走 Anthropic Messages 协议，base_url 填 https://www.tokenstack.cc，不带 /v1；api_mode 必须是 anthropic_messages，填错会被识别为 OpenAI 协议导致 404。如果想用 GPT/Gemini 等模型，改成 base_url: "https://www.tokenstack.cc/v1" + api_mode: "chat_completions" + default: "gpt-4o"。

Claude Code

Claude Code 是 Anthropic 官方的 AI 编程 CLI 工具，通过环境变量配置 API 端点。

配置环境变量

先选你的操作系统（页面已根据你的设备自动选好）：

第一步：编辑 shell 配置文件（macOS 是 ~/.zshrc，Linux 和 WSL 是 ~/.bashrc），在文件末尾追加以下两行：

~/.zshrc 或 ~/.bashrc 
export ANTHROPIC_API_KEY="sk-你的密钥"
export ANTHROPIC_BASE_URL="https://www.tokenstack.cc"

第二步：保存文件后，在终端运行以下命令让配置立即生效（Linux / WSL 改为 source ~/.bashrc）：

终端 
source ~/.zshrc

第一步：打开 PowerShell（开始菜单搜「PowerShell」），运行以下两行命令（CMD 也可以）：

PowerShell / CMD 
setx ANTHROPIC_API_KEY "sk-你的密钥"
setx ANTHROPIC_BASE_URL "https://www.tokenstack.cc"

第二步：关闭当前终端窗口，重新打开一个新的。setx 写入的环境变量只对新开的终端生效——这是 Windows 上最容易踩的坑，命令明明执行成功了却不生效，多半是没重开终端。

验证配置

在终端输入 claude 启动 Claude Code，发送一条消息。如果正常回复，说明配置成功。

🖼️
截图待补充：Claude Code 终端配置成功后的对话
注意：Claude Code 使用 Anthropic Messages API，Base URL 为 https://www.tokenstack.cc，不带 /v1。这是和其他工具最大的区别，填错会导致请求失败。

Codex CLI

Codex 是 OpenAI 官方的 AI 编程 CLI 工具，可以通过环境变量或 ~/.codex/config.toml 接入 TokenStack。下面两种方式任选其一。

方式一：环境变量（最简单）

编辑 shell 配置文件（macOS 是 ~/.zshrc，Linux 和 WSL 是 ~/.bashrc），追加以下两行：

~/.zshrc 或 ~/.bashrc 
export OPENAI_API_KEY="sk-你的TokenStack密钥"
export OPENAI_BASE_URL="https://www.tokenstack.cc/v1"

保存后执行 source ~/.zshrc（Linux / WSL 是 source ~/.bashrc）让配置生效，然后输入 codex 启动。

打开 PowerShell（或 CMD），运行以下两行命令：

PowerShell / CMD 
setx OPENAI_API_KEY "sk-你的TokenStack密钥"
setx OPENAI_BASE_URL "https://www.tokenstack.cc/v1"

然后关闭当前终端，重新打开一个新的（setx 只对新终端生效），输入 codex 启动。

方式二：config.toml 自定义 Provider（进阶）

如果你已经用环境变量配了官方 OpenAI、不想被覆盖，可以新建一个独立 Provider。打开（或新建）~/.codex/config.toml（Windows 路径是 C:\Users\你的用户名\.codex\config.toml）：

~/.codex/config.toml 
model_provider = "tokenstack"
model = "gpt-4o"

[model_providers.tokenstack]
name = "TokenStack"
base_url = "https://www.tokenstack.cc/v1"
env_key = "TOKENSTACK_API_KEY"
wire_api = "chat"

再设置密钥环境变量（变量名必须和上面的 env_key 一致）：

~/.zshrc 或 ~/.bashrc 
export TOKENSTACK_API_KEY="sk-你的TokenStack密钥"
PowerShell / CMD 
setx TOKENSTACK_API_KEY "sk-你的TokenStack密钥"

运行后记得重开终端才生效。

验证

终端执行 codex，发送一条消息，能正常响应说明配置成功。

🖼️
截图待补充：Codex CLI 配置成功后的对话
注意：
  • Codex 是 OpenAI 系工具，base_url 必须带 /v1（和 Claude Code 相反）。
  • 新版 Codex CLI 默认走 Responses API；TokenStack 是 Chat Completions 网关，所以 wire_api 显式设为 "chat"，不要写 "responses"。
  • model 字段写你想用的模型名，比如 gpt-4o、gpt-5，到 www.tokenstack.cc 后台可查看完整可用列表。

Cursor

Cursor 是一款 AI 驱动的代码编辑器，通过内置设置界面配置自定义 API 端点。

配置步骤

1

打开 Cursor Settings

点击 Cursor 右上角的齿轮图标，进入 Cursor Settings。

注意：是 Cursor Settings，不是 VS Code Settings（快捷键打开的那个）。

2

进入 Models 标签页

在设置页面顶部选择 Models 标签。

3

填写 API 配置

  • Override OpenAI Base URL：https://www.tokenstack.cc/v1
  • API Key：填入你的 TokenStack 密钥（sk-xxx）
4

验证并保存

点击 Verify 按钮验证连通性，显示成功后点击 Save 保存。

🖼️
截图待补充：Cursor Settings → Models 配置界面
注意：自定义 API Key 仅对聊天模型生效，Tab 自动补全仍使用 Cursor 内置模型，不消耗 TokenStack 额度。

Windsurf

Windsurf 是另一款 AI 代码编辑器，配置方式与 Cursor 类似，通过设置界面操作。

配置步骤

1

打开设置

打开 Windsurf，进入 Settings（设置）页面。

2

搜索 API 配置

在设置搜索框中输入 "API" 或 "Provider"，找到 API 配置区域。

3

填写配置信息

  • API Base URL：https://www.tokenstack.cc/v1
  • API Key：填入你的 TokenStack 密钥
4

保存设置

保存后即可在 Windsurf 中使用 TokenStack 的模型。

🖼️
截图待补充：Windsurf 设置界面

Cline

Cline 是一款 VS Code 扩展，提供 AI 编程辅助功能。通过扩展面板的设置界面配置。

配置步骤

1

打开 Cline 设置

在 VS Code 侧边栏打开 Cline 面板，点击右上角的齿轮图标进入 Settings。

2

选择 API Provider

在 API Provider 下拉菜单中选择 "OpenAI Compatible"。

3

填写配置信息

  • Base URL：https://www.tokenstack.cc/v1
  • API Key：填入你的 TokenStack 密钥
  • Model ID：手动输入模型名称，如 claude-sonnet-4-6
4

验证配置

保存后在 Cline 面板中发送一条消息，确认模型正常响应。

🖼️
截图待补充：Cline 设置界面 — 选择 OpenAI Compatible 并填写配置
注意：API Provider 要选 "OpenAI Compatible"，不要选 "Claude"（那个只能连 Anthropic 官方）。Model ID 是手动输入的文本框，不是下拉选择，请确保模型名称拼写正确。

ChatBox

ChatBox 是一款跨平台的 AI 聊天桌面应用，支持添加自定义 API Provider。

配置步骤

1

打开设置

打开 ChatBox，点击侧边栏的设置图标，进入 Model 标签页。

2

添加自定义 Provider

点击 Model Provider 下拉菜单，选择 "Add Custom Provider"（添加自定义提供商）。

3

填写配置信息

  • API Mode：选择 "OpenAI API Compatible"
  • Name：TokenStack（自定义名称）
  • API Host：https://www.tokenstack.cc/v1/
  • API Key：填入你的 TokenStack 密钥
  • Model：输入模型名称，如 claude-sonnet-4-6
4

开始对话

保存后回到聊天界面，选择刚添加的 Provider 和模型，发送消息验证。

🖼️
截图待补充：ChatBox 添加自定义 Provider 界面

LobeChat

LobeChat 是一款开源的 AI 聊天 UI，支持自部署或直接使用在线版本。通过设置界面配置自定义 API 端点。

配置步骤

1

进入语言模型设置

点击左下角 Actions → Settings → 选择 "Language Model" 标签页。

2

选择 OpenAI 配置

在语言模型列表中选择 OpenAI。

3

填写配置信息

  • API Key：填入你的 TokenStack 密钥
  • API Proxy Address（代理地址）：https://www.tokenstack.cc/v1
  • 勾选 "使用客户端请求模式"（Use Client-Side Fetching Mode）
4

获取模型列表

点击 "Get Model List" 按钮，系统会自动拉取 TokenStack 支持的模型列表。选择你需要的模型即可开始对话。

🖼️
截图待补充：LobeChat Settings → Language Model → OpenAI 配置界面
提示：如果 AI 返回空消息或报错，尝试在代理地址末尾加上或去掉 /v1。不同版本的 LobeChat 对这个后缀的处理可能不同。

Obsidian Copilot

Obsidian 是一款流行的笔记应用，通过安装 Copilot 插件可以在笔记中使用 AI 功能。

第一步：安装 Copilot 插件

1

打开 Obsidian → Settings → Community Plugins → Browse → 搜索 "Copilot" → 安装并启用。

第二步：配置 API 端点

2

进入 Settings → Community Plugins → Copilot → Settings，找到自定义模型配置区域。

3

添加自定义模型

  • Provider：选择 "OpenAI" 或 "OpenAI Compatible"
  • Base URL：https://www.tokenstack.cc/v1
  • API Key：在 Basic Settings → API Keys 区域填入你的 TokenStack 密钥
  • Model Name：手动输入模型名称

第三步：验证

4

回到笔记中，使用 Copilot 的对话功能（通常是侧边栏或命令面板），发送一条消息确认连通。

🖼️
截图待补充：Obsidian Copilot 插件设置界面

API 参考

以下为 TokenStack 提供的特色 API 接口文档，适合开发者直接调用。

GPT Image 2 图片 API

使用 GPT Image 2 模型进行图片生成与编辑，支持文本渲染、最高 4K 分辨率。提供同步与异步两种调用方式。

接口列表

接口 方法 端点 说明
同步图片生成 POST /v1/images/generations 等待响应直接返回结果
同步图片编辑 POST /v1/images/edits 基于原图编辑，直接返回结果
异步提交生成 POST /v1/images/async/generations 提交任务，立即返回 task_id
异步提交编辑 POST /v1/images/async/edits 提交编辑任务，立即返回 task_id
查询任务状态 GET /v1/images/async/{type}/{task_id} 轮询查询任务进度，{type} 取 generations 或 edits

同步图片生成

提交后等待响应直接返回结果，适合单张 / 快速生成场景。

API 端点

POST 
https://www.tokenstack.cc/v1/images/generations

请求参数

请求体格式：application/json

参数 类型 必填 说明
model string 是 模型名称，填 gpt-image-2
prompt string 是 图片描述文本
n integer 否 生成数量，默认 1，每张独立计费
size string 否 auto（默认）/ 1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 3840x2160
约束：最大边 ≤ 3840px、两边均为 16 倍数、长短比 ≤ 3:1、像素数 655,360 ~ 8,294,400
quality string 否 low / medium / high / auto（默认）
response_format string 否 b64_json（默认，base64 编码）/ url（图片直链，1 小时有效）

请求示例

Python 
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的TokenStack密钥",
    base_url="https://www.tokenstack.cc/v1"
)

response = client.images.generate(
    model="gpt-image-2",
    prompt="一只可爱的机器人在画风景画",
    size="1024x1024",
    quality="high",
    n=1,
    response_format="url"
)

image_url = response.data[0].url
print(image_url)
cURL 
curl https://www.tokenstack.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的TokenStack密钥" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只可爱的机器人在画风景画",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url"
  }'

响应格式

response_format=url

JSON 
{
  "created": 1234567890,
  "data": [
    {
      "url": "https://www.tokenstack.cc/images/xxx.png",
      "revised_prompt": "优化后的提示词"
    }
  ]
}

response_format=b64_json（默认）

JSON 
{
  "created": 1234567890,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRg...",
      "revised_prompt": "优化后的提示词"
    }
  ]
}

同步图片编辑

基于已有图片进行编辑修改，支持局部重绘（使用 mask 指定编辑区域），可一次传入多张参考图。

API 端点

POST 
https://www.tokenstack.cc/v1/images/edits

请求参数

请求体格式：multipart/form-data

参数 类型 必填 说明
model string 是 模型名称，填 gpt-image-2
image file 是 待编辑的原始图片，PNG 格式。支持多张：重复传 image 字段即可
prompt string 是 编辑描述，说明需要如何修改图片
mask file 否 遮罩图片（PNG），必须包含 alpha 通道，尺寸需与 image 一致，最大 50MB。多图时遮罩应用于第一张
size string 否 auto（默认）/ 1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 3840x2160
约束：最大边 ≤ 3840px、两边均为 16 倍数、长短比 ≤ 3:1
quality string 否 low / medium / high / auto（默认）
n integer 否 生成数量，默认 1
response_format string 否 b64_json（默认，base64 编码）/ url（图片直链，1 小时有效）

请求示例

Python 
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的TokenStack密钥",
    base_url="https://www.tokenstack.cc/v1"
)

response = client.images.edit(
    model="gpt-image-2",
    image=open("original.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="把背景换成星空",
    size="1024x1024",
    n=1,
    response_format="url"
)

image_url = response.data[0].url
print(image_url)
cURL（单图编辑） 
curl https://www.tokenstack.cc/v1/images/edits \
  -H "Authorization: Bearer sk-你的TokenStack密钥" \
  -F "model=gpt-image-2" \
  -F "image=@original.png" \
  -F "mask=@mask.png" \
  -F "prompt=把背景换成星空" \
  -F "size=1024x1024" \
  -F "n=1" \
  -F "response_format=url"
cURL（多图参考） 
curl https://www.tokenstack.cc/v1/images/edits \
  -H "Authorization: Bearer sk-你的TokenStack密钥" \
  -F "model=gpt-image-2" \
  -F "image=@source1.png" \
  -F "image=@source2.png" \
  -F "prompt=保留主体构图，把背景改成雨夜霓虹街道" \
  -F "size=1024x1024" \
  -F "quality=high"

异步接口

批量生成、不希望长时间保持 HTTP 连接、或希望直接拿图片 URL 而非 base64 时使用。提交后立即返回 task_id，通过轮询查询状态获取结果。

提交异步生成任务

POST https://www.tokenstack.cc/v1/images/async/generations

请求体格式：application/json，参数与同步生成接口一致（model、prompt、n、size、quality、response_format）。

请求示例

cURL 
curl -X POST https://www.tokenstack.cc/v1/images/async/generations \
  -H "Authorization: Bearer sk-你的TokenStack密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "未来主义城市黄昏景观，电影级光影",
    "size": "1536x1024",
    "quality": "high"
  }'
Python 
import requests

API_BASE = "https://www.tokenstack.cc"
API_KEY = "sk-你的TokenStack密钥"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

resp = requests.post(
    f"{API_BASE}/v1/images/async/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-2",
        "prompt": "未来主义城市黄昏景观，电影级光影",
        "size": "1536x1024",
        "quality": "high"
    }
)
task = resp.json()
task_id = task["id"]
print(f"任务已提交: {task_id}")

提交成功响应

JSON 
{
  "id": "task_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "status": "pending",
  "model": "gpt-image-2",
  "created_at": 1711008000
}

提交异步编辑任务

POST https://www.tokenstack.cc/v1/images/async/edits

请求体格式：multipart/form-data，参数与同步编辑接口一致（model、prompt、image、mask、n、size、quality、response_format），同样支持多张参考图（重复 image 字段）。

请求示例

cURL 
curl -X POST https://www.tokenstack.cc/v1/images/async/edits \
  -H "Authorization: Bearer sk-你的TokenStack密钥" \
  -F "model=gpt-image-2" \
  -F "prompt=保留主体构图，把背景改成雨夜霓虹街道" \
  -F "image=@/path/to/source1.png" \
  -F "image=@/path/to/source2.png" \
  -F "size=1024x1024" \
  -F "quality=high"
Python 
import requests

API_BASE = "https://www.tokenstack.cc"
API_KEY = "sk-你的TokenStack密钥"

with open("source.png", "rb") as image_file:
    task = requests.post(
        f"{API_BASE}/v1/images/async/edits",
        headers={"Authorization": f"Bearer {API_KEY}"},
        data={
            "model": "gpt-image-2",
            "prompt": "把背景改成星空",
            "size": "1024x1024",
            "quality": "high",
        },
        files={"image": ("source.png", image_file, "image/png")},
    ).json()

task_id = task["id"]
print(f"任务已提交: {task_id}")

查询任务状态

提交后通过 GET 请求轮询，端点取决于任务类型：

  • 生成任务：GET /v1/images/async/generations/{task_id}
  • 编辑任务：GET /v1/images/async/edits/{task_id}

请求头需带 Authorization: Bearer sk-你的密钥。

状态值

status 含义 响应额外字段
pending 排队中或正在生成 —
complete 全部图片生成成功 + data
partial_complete 部分成功（n > 1 时），失败部分自动退还额度 + data（成功部分）
+ error
failed 全部失败，预扣额度全额退还 + error（error.message 含原因）

响应示例

以 complete 为例。其他状态下 data 或 error 的有无见上表。

JSON 
{
  "id": "task_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "status": "complete",
  "model": "gpt-image-2",
  "created_at": 1711008000,
  "data": [
    {
      "url": "https://www.tokenstack.cc/images/req_abc123_0.png"
    }
  ]
}

完整端到端示例（Python 轮询）

Python 
import requests
import time

API_BASE = "https://www.tokenstack.cc"
API_KEY = "sk-你的TokenStack密钥"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. 提交任务
resp = requests.post(
    f"{API_BASE}/v1/images/async/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-2",
        "prompt": "未来主义城市黄昏景观，电影级光影",
        "size": "1536x1024",
        "quality": "high"
    }
)
task_id = resp.json()["id"]
print(f"任务已提交: {task_id}")

# 2. 轮询查询（推荐 3 秒间隔）
while True:
    result = requests.get(
        f"{API_BASE}/v1/images/async/generations/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    ).json()

    status = result["status"]

    if status == "complete":
        for img in result["data"]:
            print(f"图片 URL: {img['url']}")
        break
    elif status == "partial_complete":
        print(f"部分成功: {result['error']['message']}")
        for img in result["data"]:
            print(f"图片 URL: {img['url']}")
        break
    elif status == "failed":
        print(f"生成失败: {result['error']['message']}")
        break
    else:
        print("生成中...")
        time.sleep(3)

计费规则（异步）

  • 提交时按 模型单价 × N 预扣费
  • 全部成功：扣费生效
  • 部分成功：仅扣已成功部分，失败部分自动退还额度
  • 全部失败：预扣额度全额退还

使用提示

  • response_format=url 时，图片 URL 有效期为 1 小时，请及时下载保存
  • 默认 response_format=b64_json，返回 base64 编码图片，无外链依赖
  • 模型支持在图片中渲染文字，直接在 prompt 中描述即可
  • 需要透明背景时，在 prompt 中显式描述（如"透明背景的 PNG 图标"）
  • 编辑接口：mask 的透明区域即为重绘区域，其余部分保持不变；mask 必须包含 alpha 通道，且尺寸与 image 一致
  • 多张参考图：image 字段重复传递即可，传多张时 mask 应用于第一张
  • 异步任务推荐轮询间隔 3 秒；批量生成（n > 1）建议使用异步接口
  • 详细的描述能获得更好的生成效果

HTTP 错误码

状态码 含义
400请求参数错误
401认证失败（API Key 无效）
402额度不足
403内容策略违规
404任务不存在（仅异步查询）
429速率限制
502 / 503上游服务错误或无可用渠道

NanoBanana 图片 API

基于 Google Gemini 系列模型的图片生成接口，俗称 NanoBanana。支持文生图、图片编辑、多图合成、多轮对话式生成，最高 4K 分辨率。同步接口——请求直接返回 base64 图片数据，不需要轮询任务；需要图片 URL 直接落地的场景请改用 GPT Image 2（支持 response_format=url）。

模型概览

模型 俗称 主要特点 适用场景
gemini-3.1-flash-image-preview NanoBanana 2 性价比与速度最均衡；支持 512px ~ 4K、图片搜索接地、思考等级控制 推荐首选，日常图片生成
gemini-3-pro-image-preview NanoBanana Pro 支持 4K、高级推理、Google 搜索接地，最多 14 张参考图 专业素材制作、复杂指令

接口列表

接口 方法 端点 说明
文本生成图片 POST /v1beta/models/{model}:generateContent 通过 prompt 直接生成图片
参考图编辑 POST /v1beta/models/{model}:generateContent 同一端点，传入一张参考图做编辑 / 重绘 / 风格迁移
多图合成 POST /v1beta/models/{model}:generateContent 同一端点，传入多张参考图融合成一张
多轮对话式生成 POST /v1beta/models/{model}:generateContent 同一端点，维持上下文做迭代修改

Base URL：https://www.tokenstack.cc

鉴权方式：NanoBanana 走 Gemini 原生协议，鉴权使用 URL 查询参数 ?key=sk-你的TokenStack密钥，不是 Authorization 请求头。这是和 OpenAI 系列接口最大的区别，填错会导致 401。

请求格式：application/json。

文本生成图片

最常用模式：传入文本描述，直接生成图片。

API 端点

POST 
https://www.tokenstack.cc/v1beta/models/gemini-3-pro-image-preview:generateContent?key=sk-你的TokenStack密钥

请求参数

请求体格式：application/json

参数 类型 必填 说明
contents array 是 提示内容数组，至少包含一段 {"text": "..."}
generationConfig object 否 生成配置容器
generationConfig.responseModalities array 否 ["IMAGE"] 仅返回图片；["TEXT", "IMAGE"] 同时返回文本说明（默认）
generationConfig.imageConfig.aspectRatio string 否 宽高比：1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9；3.1 Flash 还支持 1:4 / 4:1 / 8:1
generationConfig.imageConfig.imageSize string 否 图片尺寸（仅 Gemini 3 系列支持）：512px / 1K / 2K / 4K。必须大写 K，小写会被拒绝

请求示例

Python 
from google import genai
from google.genai import types

client = genai.Client(
    api_key="sk-你的TokenStack密钥",
    http_options={"base_url": "https://www.tokenstack.cc"}
)

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=["一只小猫在阳光下玩耍"],
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
            image_size="2K",
        ),
    ),
)

for part in response.candidates[0].content.parts:
    if part.inline_data is not None:
        image = part.as_image()
        image.save("output.png")
        print("图片已保存为 output.png")
        break
    elif part.text:
        print("文本响应:", part.text)
cURL 
curl -s -X POST \
  "https://www.tokenstack.cc/v1beta/models/gemini-3-pro-image-preview:generateContent?key=sk-你的TokenStack密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "一只小猫在阳光下玩耍"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9"
      }
    }
  }' \
  | grep -o '"data": "[^"]*"' \
  | cut -d'"' -f4 \
  | base64 --decode > output.png

响应格式

JSON 
{
  "candidates": [{
    "content": {
      "parts": [{
        "inlineData": {
          "mimeType": "image/png",
          "data": "<BASE64_IMAGE_DATA>"
        }
      }],
      "role": "model"
    },
    "finishReason": "STOP"
  }],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1300
  }
}
图片在哪？取 candidates[0].content.parts[] 里带 inlineData 的那一项，inlineData.data 就是 base64 编码的 PNG，解码保存即可（上面 curl 示例最后一段管道就是在干这个）。usageMetadata 是本次消耗的令牌数，用于核对计费。

参考图编辑

在 contents 中同时传入文本与一张参考图（inline_data base64 形式），就能对图片做编辑、局部重绘、风格迁移。仅支持 base64 内联上传，不支持图片 URL。需要多张参考图请看多图合成。

1. 单图编辑（给猫加巫师帽）

Python 
from google import genai
from PIL import Image

client = genai.Client(
    api_key="sk-你的TokenStack密钥",
    http_options={"base_url": "https://www.tokenstack.cc"}
)

image = Image.open("input.jpg")

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        "给图中这只猫戴上一顶巫师帽",
        image,
    ],
)

for part in response.candidates[0].content.parts:
    if part.inline_data is not None:
        part.as_image().save("edited.png")
        print("已保存 edited.png")
        break
cURL 
IMG_BASE64=$(base64 -w0 input.jpg)

curl -X POST \
  "https://www.tokenstack.cc/v1beta/models/gemini-3-pro-image-preview:generateContent?key=sk-你的TokenStack密钥" \
  -H 'Content-Type: application/json' \
  -d "{
    \"contents\": [{
      \"parts\": [
        {\"text\": \"给图中这只猫戴上一顶巫师帽\"},
        {
          \"inline_data\": {
            \"mime_type\": \"image/jpeg\",
            \"data\": \"$IMG_BASE64\"
          }
        }
      ]
    }]
  }" \
  | grep -o '"data": "[^"]*"' \
  | cut -d'"' -f4 \
  | base64 --decode > edited.png

2. 局部重绘（只换沙发）

Python 
from google import genai
from PIL import Image

client = genai.Client(
    api_key="sk-你的TokenStack密钥",
    http_options={"base_url": "https://www.tokenstack.cc"}
)

living_room = Image.open("living_room.png")

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        living_room,
        "把图中那张蓝色沙发换成复古棕色皮质 Chesterfield 沙发，"
        "其它部分保持不变。",
    ],
)

for part in response.candidates[0].content.parts:
    if part.inline_data is not None:
        part.as_image().save("living_room_edited.png")
        break

3. 风格迁移（梵高星空风格）

Python 
from google import genai
from PIL import Image

client = genai.Client(
    api_key="sk-你的TokenStack密钥",
    http_options={"base_url": "https://www.tokenstack.cc"}
)

city_image = Image.open("city.png")

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        city_image,
        "把这张照片改成梵高《星空》风格：保留原构图，"
        "全部元素用旋转的厚涂笔触和深蓝、亮黄色调渲染。",
    ],
)

for part in response.candidates[0].content.parts:
    if part.inline_data is not None:
        part.as_image().save("city_style_transfer.png")
        break

局部重绘、风格迁移的 JSON 结构与单图编辑完全相同，只需要换 text 里的指令。macOS 用户请把 base64 -w0 改为 base64 -i。

多图合成

一次传入多张参考图，让模型把它们融到同一张图里——电商换装、产品放进场景、人物合影都是这个玩法。提示词里要指明每张图的用途（第一张是什么、第二张是什么）。参考图数量上限见限制说明。

示例：把衣服穿到模特身上（电商换装）

Python 
from google import genai
from PIL import Image

client = genai.Client(
    api_key="sk-你的TokenStack密钥",
    http_options={"base_url": "https://www.tokenstack.cc"}
)

dress_image = Image.open("dress.png")
model_image = Image.open("model.png")

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        dress_image,
        model_image,
        "生成一张专业电商时尚照：让第二张图的女士穿上第一张图的蓝色碎花连衣裙，"
        "全身实拍效果，自然光线与阴影。",
    ],
)

for part in response.candidates[0].content.parts:
    if part.inline_data is not None:
        part.as_image().save("fashion_photo.png")
        break
cURL（多张参考图就是多个 inline_data 并列） 
DRESS_B64=$(base64 -w0 dress.png)
MODEL_B64=$(base64 -w0 model.png)

curl -X POST \
  "https://www.tokenstack.cc/v1beta/models/gemini-3-pro-image-preview:generateContent?key=sk-你的TokenStack密钥" \
  -H 'Content-Type: application/json' \
  -d "{
    \"contents\": [{
      \"parts\": [
        {\"inline_data\": {\"mime_type\": \"image/png\", \"data\": \"$DRESS_B64\"}},
        {\"inline_data\": {\"mime_type\": \"image/png\", \"data\": \"$MODEL_B64\"}},
        {\"text\": \"生成一张专业电商时尚照：让第二张图的女士穿上第一张图的蓝色碎花连衣裙，全身实拍效果，自然光线与阴影。\"}
      ]
    }]
  }" \
  | grep -o '\"data\": \"[^\"]*\"' \
  | cut -d'\"' -f4 \
  | base64 --decode > fashion_photo.png

macOS 用户请把 base64 -w0 改为 base64 -i。需要更多张图就继续往 parts 里加 inline_data 项，顺序就是提示词里「第一张、第二张」的顺序。

多轮对话式生成

通过 chats.create 维持上下文，可以基于上一张生成的图反复迭代修改，比如「把文字改成西班牙语」「把背景换成夜晚」。

Python 示例

Python 
from google import genai
from google.genai import types

client = genai.Client(
    api_key="sk-你的TokenStack密钥",
    http_options={"base_url": "https://www.tokenstack.cc"}
)

chat = client.chats.create(
    model="gemini-3-pro-image-preview",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
    ),
)

# 第一轮：生成原图
response = chat.send_message(
    "做一张面向小学四年级学生的光合作用信息图，"
    "把整个过程画成一份'植物最爱的食谱'。"
)
for part in response.parts:
    if part.text:
        print(part.text)
    elif image := part.as_image():
        image.save("photosynthesis.png")

# 第二轮：基于上图改文字为西班牙语
response = chat.send_message(
    "把这张信息图里的所有文字改成西班牙语，其它元素都不要动。",
    config=types.GenerateContentConfig(
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
            image_size="2K",
        ),
    ),
)
for part in response.parts:
    if image := part.as_image():
        image.save("photosynthesis_spanish.png")

高分辨率输出（4K）

把 imageSize 设为 4K 即可。仅 gemini-3-pro-image-preview 与 gemini-3.1-flash-image-preview 支持。

cURL 
curl -s -X POST \
  "https://www.tokenstack.cc/v1beta/models/gemini-3-pro-image-preview:generateContent?key=sk-你的TokenStack密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "达芬奇风格的蝴蝶解剖学手绘"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "4K"
      }
    }
  }'

控制思考等级（仅 3.1 Flash）

通过 thinking_config.thinking_level 调整模型思考深度，可选 low / medium / high。注意：无论 include_thoughts 设为何值，思考令牌都会计费。

Python 
from google import genai
from google.genai import types

client = genai.Client(
    api_key="sk-你的TokenStack密钥",
    http_options={"base_url": "https://www.tokenstack.cc"}
)

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents="一座建在漂浮于太空的巨大玻璃瓶中的未来城市",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        thinking_config=types.ThinkingConfig(
            thinking_level="high",
            include_thoughts=False,
        ),
    ),
)

for part in response.parts:
    if part.thought:
        continue
    if image := part.as_image():
        image.save("city.png")

Google 搜索接地（生成基于实时信息的图片）

给请求挂上 google_search 工具后，模型会先搜索真实信息再作画——适合天气图、赛事海报、新闻配图等需要事实正确的场景。

Python 
from google import genai
from google.genai import types

client = genai.Client(
    api_key="sk-你的TokenStack密钥",
    http_options={"base_url": "https://www.tokenstack.cc"}
)

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="生成一张深圳明天天气预报的插画海报，温度和天气要真实",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        tools=[types.Tool(google_search=types.GoogleSearch())],
    ),
)

for part in response.candidates[0].content.parts:
    if part.inline_data is not None:
        part.as_image().save("weather.png")
cURL（tools 字段写法） 
curl -s -X POST \
  "https://www.tokenstack.cc/v1beta/models/gemini-3-pro-image-preview:generateContent?key=sk-你的TokenStack密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "生成一张深圳明天天气预报的插画海报，温度和天气要真实"}]
    }],
    "tools": [{"google_search": {}}],
    "generationConfig": {
      "responseModalities": ["IMAGE"]
    }
  }'

搜索接地依赖上游线路支持，如果带 tools 的请求报错，说明当前线路暂未开放此能力，去掉 tools 字段即可正常生成。

提示词技巧、分辨率与排错

提示词怎么写出好图

场景 写法要点 示例
写实图片 描述清楚主体、环境、镜头、光线、材质五要素 「一只橘猫趴在木窗台上（主体），背景是雨后的庭院（环境），85mm 浅景深（镜头），暖色夕阳侧光（光线），毛发蓬松细腻（材质）」
产品图 明确背景、角度、阴影，以及品牌文字要不要出现 「白色无缝背景，45 度俯拍，柔和的自然投影，瓶身上保留 LOGO 文字清晰可读」
图片编辑 说明「保留什么」和「只修改什么」 「保留人物姿势、表情和光线不变，只把背景换成夜晚的城市天台」
多图合成 指明每张参考图的用途 「第一张图是产品，第二张图是场景，把产品自然地放进场景的桌面上」
图中带文字 先说清楚要写什么字，再描述画面 「海报主标题写：双十一 5 折起（这几个字必须准确出现），背景为红金色促销氛围」

常见问题速查

现象 处理方式
返回了文本没有图片 检查 generationConfig.responseModalities 是否包含 "IMAGE"
401 鉴权失败 NanoBanana 用 URL 参数 ?key=sk-xxx 鉴权，不是 Authorization 头；确认密钥完整
参数被拒绝 / 400 Gemini 原生格式区分大小写：检查 inlineData / mimeType / imageSize 的驼峰写法，imageSize 的值必须大写 K（1K 不是 1k）
想直接拿图片 URL 本接口只返回 base64。需要 URL 的场景改用 GPT Image 2（response_format=url）
要求 3 张只回了 2 张 模型不保证严格按数量返回，批量出图建议循环多次请求，每次一张

gemini-3.1-flash-image-preview 分辨率（NanoBanana 2）

支持 512px / 1K / 2K / 4K 四档，括号内为令牌数：

宽高比 512px 1K 2K 4K
1:1512x512 (747)1024x1024 (1120)2048x2048 (1120)4096x4096 (2000)
2:3424x632 (747)848x1264 (1120)1696x2528 (1120)3392x5056 (2000)
3:2632x424 (747)1264x848 (1120)2528x1696 (1120)5056x3392 (2000)
3:4448x600 (747)896x1200 (1120)1792x2400 (1120)3584x4800 (2000)
4:3600x448 (747)1200x896 (1120)2400x1792 (1120)4800x3584 (2000)
4:5464x576 (747)928x1152 (1120)1856x2304 (1120)3712x4608 (2000)
5:4576x464 (747)1152x928 (1120)2304x1856 (1120)4608x3712 (2000)
9:16384x688 (747)768x1376 (1120)1536x2752 (1120)3072x5504 (2000)
16:9688x384 (747)1376x768 (1120)2752x1536 (1120)5504x3072 (2000)
21:9792x168 (747)1584x672 (1120)3168x1344 (1120)6336x2688 (2000)

参考图数量限制

模型 对象图 人物图 合计上限
gemini-3.1-flash-image-preview10 张4 张14 张
gemini-3-pro-image-preview6 张5 张14 张

注意事项

  • 鉴权方式：用 URL 查询参数 ?key=sk-你的TokenStack密钥，不是 Authorization: Bearer 头，这是 NanoBanana 接口和其他接口最大的区别。
  • 仅支持 base64 图片：所有参考图必须通过 inline_data 字段以 base64 编码上传，不支持图片 URL。
  • 不支持音视频输入：仅接受文本和图片，音频/视频输入不可用。
  • imageSize 必须大写：填 1K / 2K / 4K，小写会被拒绝。
  • SynthID 水印：所有生成的图片都包含 SynthID 不可见水印。
  • 输出数量：模型不一定严格按要求的图片数量返回，可能多也可能少。
  • 文字渲染：需要在图中生成文字时，建议先用文本说清楚要写什么，再要求生成图片。
  • 思考令牌计费：使用 thinking_level 时，思考令牌无论是否返回都会计费。

视频生成 API（统一格式）

TokenStack 全部视频档位共用同一套接口——同一个端点、同一份请求体、同一套状态机，换模型只改 model 一个字段。走标准 OpenAI 兼容格式，任务异步执行：提交后立即返回任务 id，轮询查询结果。

🚀 对接速查（给你 / 你的程序员）
  • 提交：POST https://www.tokenstack.cc/v1/videos
  • 查询：GET https://www.tokenstack.cc/v1/videos/{id}
  • 鉴权：Authorization: Bearer sk-你的TokenStack密钥
  • 模型名：见下方档位一览，只有 model 值不同，请求体结构完全一样
  • 请求体（JSON）：
JSON 
{
  "model": "seedance-720p-931-pro",
  "prompt": "海边日落，金毛犬追逐浪花，慢镜头",
  "duration": 15,
  "seconds": "15",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "images": ["https://你的图床.com/role.jpg"]
}

❗素材必须是公网 https 直链——base64、本地路径、需登录才能打开的地址都会失败，详见素材准备。

✅ 这次统一了什么（老用户请看）
  • 过去 Seedance 有 4 套请求格式（Sora 平铺、input/parameters、另一套 JSON、reference_* 平铺），现在只剩本页这一套。
  • 档位名是长期稳定的契约：背后换供应商、上游改名，你这边不用改代码。
  • 老的 Seedance / Grok Imagine / Omni Flash 系列模型名已下线，请按下方档位表换成新模型名。

档位一览

状态档位名（填进 model）画质 · 分辨率时长 · 计费参考素材上限
图片音频视频
✅ 已开放seedance-720p-931-pro满血 · 720p15 秒 · 按次0~9 张 · 可不传≤ 3 段≤ 1 段
🕐 即将开放seedance-720p-930-pro满血 · 720p15 秒 · 按次0~9 张 · 可不传≤ 3 段❌
✅ 已开放seedance-720p-931-fast快速 · 720p15 秒 · 按次0~9 张 · 可不传≤ 3 段≤ 1 段
🕐 即将开放seedance-720p-930-fast快速 · 720p15 秒 · 按次0~9 张 · 可不传≤ 3 段❌
✅ 已开放seedance-720p-410-fast快速 · 720p15 秒 · 按次1~4 张 · 必传≤ 1 段❌
✅ 已开放seedance-720p-410-minimini · 720p15 秒 · 按次1~4 张 · 必传≤ 1 段❌
✅ 已开放seedance-480p-410-minimini · 480p15 秒 · 按次1~4 张 · 必传≤ 1 段❌
🕐 即将开放seedance-720p-410-mini-secmini · 720p5/10/15 秒 · 按秒0~4 张 · 可不传≤ 1 段❌
🕐 即将开放seedance-480p-410-mini-secmini · 480p10/15 秒 · 按秒1~4 张 · 必传≤ 1 段❌
✅ 已开放omni-720p-10s-300720p10 秒 · 按次0/1/3 张 · 不能 2 张❌❌
🕐 即将开放omni-1080p-10s-3001080p10 秒 · 按次0/1/3 张 · 不能 2 张❌❌

🕐 「即将开放」= 目前控制台还没上，调用会报错，请先用「已开放」的档位。以控制台模型列表为准——列表里有的才能调。各档位单价见 控制台价格页（会调整，别写死在代码里）。

画幅与出片时间

档位支持画幅（aspect_ratio）出片时间（实测）
全部 seedance-* 档位16:9 横屏 / 9:16 竖屏约 3~6 分钟
omni-720p-10s-30016:9 横屏 / 9:16 竖屏约 2 分钟
omni-1080p-10s-300⚠️ 仅 16:9 横屏约 2 分钟

档位名怎么读

分辨率 - 能力三位数 - 画质 [-sec]

  • 能力三位数按「图 - 音 - 视」顺序，就是三类参考素材各能传几个：931 = 9 张图、3 段音频、1 段视频；930 = 9 图 3 音 0 视；410 = 4 图 1 音 0 视；omni 的 300 = 3 图 0 音 0 视。
  • 画质：pro 满血 > fast 快速 > mini。同一档位内画质只升不降，后台故障切换不会偷偷给你降档。
  • -sec 结尾 = 按秒计费（时长可选）；不带 -sec = 按次计费（时长固定）。
  • 930 和 931 只差第三位：931 能传 1 段参考视频，930 不能。其余画质、时长、图片和音频上限完全一样。

怎么选档位

你的需求可用档位
不传任何参考图（纯文字生视频）seedance-720p-931-pro / -931-fast / omni-720p-10s-300
要参考音频（氛围音乐 / 音效）全部 seedance-* 档位（omni 不支持音频）
要 15 秒成片全部 seedance-* 档位
要出片快（约 2 分钟）omni-720p-10s-300
要 1080pomni-1080p-10s-300（🕐 即将开放，仅横屏）
要最多 9 张参考图seedance-720p-931-pro / -931-fast
要传参考视频（参考运镜 / 动作）seedance-720p-931-pro / -931-fast（各 1 段）
要自选时长（不是固定 15 秒）seedance-720p-410-mini-sec / seedance-480p-410-mini-sec（🕐 即将开放）

这几档都支持生成真人画面（过脸），但具体某一条会不会被内容审核拦下没法提前预判。选好后把示例里的 model 换成对应档位名即可，其余代码一行都不用改。

接口列表

接口方法端点说明
提交视频任务POST/v1/videos立即返回任务 id，不阻塞等待
查询任务状态GET/v1/videos/{id}轮询查询进度，完成后返回视频地址
⚠️ /v1/videos 是所有视频档位的共用端点，靠 model 字段路由。model 拼错会报错或路由到别的模型，务必从档位表或控制台复制，别手打。

Base URL：https://www.tokenstack.cc

鉴权方式：Authorization: Bearer sk-你的TokenStack密钥，标准 OpenAI 兼容格式。

请求格式：application/json。

提交视频任务

提交后立即返回任务 id，不会阻塞等待视频生成完成。

API 端点

POST 
https://www.tokenstack.cc/v1/videos

请求头

  • Authorization: Bearer sk-你的TokenStack密钥（必填）
  • Content-Type: application/json（必填）

请求参数

请求体格式：application/json

参数类型必填说明
modelstring是档位名，见档位一览。从表里或控制台复制，别手打
promptstring是提示词，描述想要的画面、镜头、风格
durationnumber是时长（秒）。必须是该档位支持的值：seedance-* 不带 -sec 的一律填 15；omni-* 一律填 10；-sec 按秒档按档位表里的可选值填。按秒档不传会被按 4 秒计费
secondsstring否duration 的字符串写法，值填一样（如 "15"）。两个都带上兼容性最好
aspect_ratiostring否画幅：16:9 横屏 / 9:16 竖屏。omni-1080p-10s-300 只支持 16:9，填 9:16 会被 400 拦截
resolutionstring否与档位名里的分辨率一致即可：480p / 720p / 1080p
sizestring否像素尺寸，720p 档可填 1280x720（横）/ 720x1280（竖）。不传就由 aspect_ratio + 档位分辨率决定，一般不用传
imagesarray看档位参考图，公网 https URL 数组。张数上限、是否必传见档位表；omni-* 档只接受 0 / 1 / 3 张，不支持 2 张。base64 会被拒，本地图先传到公网可访问的地址，见素材准备
audio_urlsarray否参考音频，公网 https URL 数组。段数上限见档位表；总时长必须 ≤ 14.5 秒（详见素材准备）。omni-* 档不支持，传了会被忽略
video_urlsarray否参考视频，公网 https URL 数组，用于参考运镜 / 动作。只有 seedance-720p-931-pro 和 seedance-720p-931-fast 支持，各最多 1 段（见档位表视频列）；其余档位不支持，传了会被忽略或直接失败。时长同样要 ≤ 14.5 秒
💡 参考素材怎么用效果最好
  • 在 prompt 里说清楚每张图的用途——例：「第一张是主角，脸型、发型、服装以它为准；第二张是场景」。说得越具体，出片越贴合参考。
  • 参考图用来锁定人物 / 商品的一致性；参考音频定氛围音乐 / 音效；参考视频定运镜 / 动作（只有 931 两档支持，各 1 段）。
  • 所有素材必须是公网 https 直链，本地文件先传到公网可访问的地址，见素材准备。

请求示例

示例 1：参考图生视频（Seedance 15 秒）

cURL 
curl https://www.tokenstack.cc/v1/videos \
  -H "Authorization: Bearer sk-你的TokenStack密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-720p-931-pro",
    "prompt": "第一张图是主角，脸型、发型、服装以它为准；第二张图是场景。15 秒横屏，镜头缓慢推进，电影感光影。",
    "duration": 15,
    "seconds": "15",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "images": [
      "https://你的图床.com/role.jpg",
      "https://你的图床.com/scene.jpg"
    ]
  }'

示例 2：参考音频 + 参考视频（Seedance 931 档）

cURL 
curl https://www.tokenstack.cc/v1/videos \
  -H "Authorization: Bearer sk-你的TokenStack密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-720p-931-fast",
    "prompt": "海边日落，金毛犬追逐浪花，慢镜头，写实风格，无字幕。运镜参考给的视频，氛围音乐参考给的音频。",
    "duration": 15,
    "seconds": "15",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio_urls": ["https://你的图床.com/bgm.mp3"],
    "video_urls": ["https://你的图床.com/camera-ref.mp4"]
  }'

⚠️ 参考音频、参考视频时长都必须 ≤ 14.5 秒，超了整单会失败——提交前务必量一下，见素材准备。video_urls 只有 931 两档能用，其他档位传了会失败。

示例 3：纯文字生视频 · 竖屏 10 秒（Omni 快速档）

cURL 
curl https://www.tokenstack.cc/v1/videos \
  -H "Authorization: Bearer sk-你的TokenStack密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-720p-10s-300",
    "prompt": "竖屏画面：金毛犬在夕阳海滩奔跑，慢镜头，写实风格，无字幕",
    "duration": 10,
    "seconds": "10",
    "aspect_ratio": "9:16",
    "resolution": "720p"
  }'

要带参考图就加 images，只能是 1 张或 3 张（2 张会被 400 拦截）。

成功响应

JSON 
{
  "id": "task_dm0E88sRQWac4L01CYFASCKBWmBOlDPa"
}

顶层 id 就是任务 ID，务必保存，下一步查询任务状态要用它。响应里可能还带别的字段，取 id 即可，其余忽略。

查询任务状态

用提交时返回的 id 轮询查询进度。出片要几分钟，务必异步轮询，别同步死等。

API 端点

GET 
https://www.tokenstack.cc/v1/videos/{id}

请求示例

cURL 
curl https://www.tokenstack.cc/v1/videos/task_dm0E88sRQWac4L01CYFASCKBWmBOlDPa \
  -H "Authorization: Bearer sk-你的TokenStack密钥"

生成中响应

JSON 
{
  "id": "task_dm0E88sRQWac4L01CYFASCKBWmBOlDPa",
  "status": "running",
  "progress": 30
}

完成响应

JSON 
{
  "id": "task_dm0E88sRQWac4L01CYFASCKBWmBOlDPa",
  "status": "completed",
  "progress": 100,
  "video_url": "https://.../vid_9902aee1.mp4"
}

响应字段

字段类型说明
idstring任务 ID，与提交时返回的一致，全程不变
statusstring只有 4 个取值：pending 排队中 / running 生成中 / completed 成功 / failed 失败
progressnumber进度 0~100，可以拿去展示进度条。但完成与否只看 status——部分渠道的 progress 不准
video_urlstringcompleted 时的成片地址，可直接播放 / 下载。约 24 小时后失效，拿到请立刻转存
error.messagestringfailed 时的失败原因，可直接展示给用户
✅ 轮询就这么写
  • 间隔 10~15 秒查一次，直到 status 变成 completed 或 failed。
  • 拿到 completed 取 video_url；拿到 failed 把 error.message 展示给用户即可。

素材准备（参考图 / 参考音频 / 参考视频）

失败单里六成是素材问题，不是接口问题。这一节的几条提交前查一下，能省掉大部分等了 5 分钟才发现失败的情况。

素材放哪儿

接口只收公网 https URL，不收 base64、不收本地路径。参考图、参考音频、参考视频都要先放到公网能直接打开的地方（对象存储、图床、你自己的静态服务器都行），再把链接填进 images / audio_urls / video_urls。

提交前必查的 4 条（不查就会失败）

#检查项要求不查会怎样
1参考音频 / 参考视频时长≤ 14.5 秒整单失败。上游硬上限是 15.00 秒，而剪出来标称「15 秒」的素材实际常是 15.0x~15.3 秒（关键帧对齐、采样率取整会多出零点几秒）——超 0.2 秒和超 5 秒后果一样，所以卡 14.5 秒留余量
2素材数量在档位表的上限内；标「必传」的档位至少 1 张图被渠道直接拒，整单失败
3素材链接可达性https 公网直链、匿名可打开拉不到素材，整单失败
4素材链接有效期≥ 30 分钟生成过程中会再次拉取素材，链接提前过期会导致整单失败
⚠️ 素材链接的坑（实测踩过）
  • http:// 开头的地址境外线路拉不到——必须 https。
  • 对象存储桶如果设了防盗链、或只允许内网访问，上游同样拉不到；要么放开公网匿名读，要么用长效签名链接。
  • 短期签名链接（几分钟就过期的）不行，见上表第 4 条。
  • 需要登录 Cookie 才能打开的地址不行。

注意事项

  • 模型名称
    请到 www.tokenstack.cc 后台复制完整的模型名称，拼写错误会导致请求失败。
  • Base URL 区别（最常见的坑）
    工具Base URL
    Claude Code、OpenClaw（Anthropic API）https://www.tokenstack.cc（不带 /v1）
    Cursor、Windsurf、Cline、ChatBox、LobeChat、Obsidian 等https://www.tokenstack.cc/v1（带 /v1）
  • 安全建议
    建议使用环境变量存储 API Key，避免将密钥明文提交到代码仓库。
  • 备份配置
    修改任何配置文件前，建议先备份原文件，以便出问题时恢复。

需要帮助？

  • 访问 www.tokenstack.cc 查看更多文档和模型列表
  • 扫描下方二维码添加微信，获取一对一技术支持
微信二维码

微信扫码添加