API 对接文档

快速开始

TokenGet 完全兼容 OpenAI API 协议。只需将已有应用的 base_url 指向本站，并使用本站签发的 API Key 即可。

  • 1. 注册账号（用户名密码或微信扫码），在控制台创建 API Key（sk-tg-...）。
  • 2. Base URL：http://<服务器地址>/v1
  • 3. 通过 GET/v1/models?category=llm 按类别拉取模型列表；一个模型可以同时属于多个分类（如 ["llm","image"]），支持 ?category=llm&category=image 取交集。
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="sk-tg-你的密钥",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}]}'

认证方式

所有 /v1/* 接口通过 HTTP Header 携带 API Key：

Authorization: Bearer sk-tg-你的密钥

网页端管理接口（/api/*）使用登录后签发的 JWT，同样放在 Authorization: Bearer 中。

大语言模型（LLM）

POST/v1/chat/completions — 支持流式（stream:true）与非流式。

{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": true
}

同时支持 POST/v1/completions 与 POST/v1/embeddings。

参数与限制

  • model（必填）：通过 GET/v1/models?category=llm 拉取当前可用模型列表；平台自动路由到优先级最高的可用上游
  • messages（必填）：OpenAI 兼容消息数组，role 支持 system / user / assistant / tool；content 支持纯文本或 [{"type":"text","text":"..."},{"type":"image_url","image_url":{"url":"..."}}] 多模态数组（具体取决于模型是否支持视觉）
  • stream：布尔值，默认 false；开启后按 SSE 流式返回
  • temperature：默认 1，范围 0–2；采样温度
  • top_p：默认 1，范围 0–1；核采样
  • max_tokens / max_completion_tokens：最大生成 token 数（模型上下文限制不同，详见模型列表）
  • frequency_penalty / presence_penalty：默认 0，范围 -2–2
  • stop：停止序列，字符串或字符串数组
  • tools / tool_choice：函数调用（模型支持时透传）
  • response_format：JSON Schema / JSON mode（模型支持时透传）
  • seed：固定随机种子（上游支持时生效）
  • 单条消息大小与总上下文长度受具体模型限制；请求体大小受 nginx 限制（1000MB）

图片生成

图片能力统一入口为 POST/v1/cap/image/{path}。调用方只需指定 model，平台根据模型自动路由到对应上游（SnapGen 原生生图接口，或 OpenRouter 多模态 LLM 的 chat.completions）。

  • POST/v1/cap/image/generate_image — 文生图 / 图生图 / 图片编辑（form-data）
  • GET/v1/cap/image/history/{uuid} — 查询单条生成结果（status == 2 即完成）
  • GET/v1/cap/image/histories — 历史列表

模型可选项

已接入的图片生成模型包括 SnapGen 原生模型（nano-banana-pro / nano-banana-2 / nano-banana-2-lite / grok-image / gpt-image-2）以及 OpenRouter 多模态 LLM（grok / gemini / inkling 等）。完整、实时列表请通过 GET/v1/models?category=image 拉取；支持多分类交集查询，如 ?category=image&category=llm。未在列表中的模型无法通过本能力路由调用。

不同上游的返回格式不同：SnapGen 原生模型返回 {"uuid": "..."} 需轮询；OpenRouter 多模态 LLM 返回 chat.completion 格式（assistant message 中携带图片 URL）。

文生图

curl http://localhost:8000/v1/cap/image/generate_image \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "prompt=a cute cat on a windowsill" \
  -F "model=nano-banana-2-lite" \
  -F "aspect_ratio=1:1"

图生图 / 图片编辑

增加 image 参数传入参考图 URL，即可图生图或风格迁移：

curl http://localhost:8000/v1/cap/image/generate_image \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "prompt=turn this into a watercolor painting" \
  -F "model=nano-banana-2-lite" \
  -F "image=https://example.com/photo.jpg" \
  -F "aspect_ratio=1:1"

本地图片直接上传（multipart/form-data）

参考图也可以本地文件随请求直接上传——image 字段值用 @文件路径，与表单字段同一请求发出，平台不设大小限制（仅网关本身的请求体上限）：

curl http://localhost:8000/v1/cap/image/generate_image \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "prompt=把这张照片变成水彩画" \
  -F "model=nano-banana-2-lite" \
  -F "image=@/Users/me/photo.jpg"

URL 与本地文件可混用；多张参考图重复传 image 字段即可。

多图参考

form-data 支持同名字段重复传参——多图参考时重复传多个 image 字段（是否生效取决于所选模型）：

curl http://localhost:8000/v1/cap/image/generate_image \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "prompt=把图1的人物放进图2的场景，保持图3的画风" \
  -F "model=nano-banana-2-lite" \
  -F "image=https://example.com/person.jpg" \
  -F "image=https://example.com/scene.jpg" \
  -F "image=https://example.com/style.jpg"

参数说明

  • prompt（必填）：画面描述 / 编辑指令
  • model（必填）：生图模型；当前可选项为 nano-banana-2-lite，实时完整列表通过 GET/v1/models?category=image 获取
  • aspect_ratio：宽高比，如 1:1 / 16:9 / 9:16
  • image：参考图，支持公网 URL 或 @本地文件路径 直接上传，可重复传多张（数量受所选模型限制）
  • image_width / image_height：输出尺寸（可选）
  • quality：hd 提升质量（可选）
  • seed：固定随机种子（可选）

轮询结果

curl http://localhost:8000/v1/cap/image/history/9f8e7d6c-xxxx \
  -H "Authorization: Bearer sk-tg-你的密钥"

status == 2 表示完成，从响应中取结果图 URL；建议每 5–10 秒轮询一次。

视频生成

视频能力统一入口为 POST/v1/cap/video/{path}。调用方只需指定 model，平台根据模型自动路由到对应上游（SnapGen / MiniMax 原生视频接口，或 OpenRouter 多模态 LLM 的 chat.completions）。

  • POST/v1/cap/video/v2/video_generation — 提交视频生成任务
  • GET/v1/cap/video/v2/query/video_generation/{task_id} — 查询任务状态

模型可选项

已接入的视频生成模型包括：

  • SnapGen 原生视频：flux-3 / veo-3
  • MiniMax 原生视频：MiniMax-H3（全功能，768P/2K，4–15s）/ MiniMax-H3-Max（更快，480P/768P，5–15s）
  • OpenRouter 多模态 LLM：grok / gemini / inkling 等

完整、实时的 model 列表请通过 GET/v1/models?category=video 拉取；支持多分类交集查询，如 ?category=video&category=llm。未在列表中的模型无法通过本能力路由调用。

不同上游的返回格式不同：SnapGen / MiniMax 原生模型返回任务 ID 需轮询；OpenRouter 多模态 LLM 返回 chat.completion 格式（assistant message 中携带视频 URL）。

1. 文生视频

content 仅含文本；ratio 必填（不能为 adaptive）。提示词支持运镜指令如 [推进]：

curl http://localhost:8000/v1/cap/video/v2/video_generation \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "一只橘猫在窗台上伸懒腰，阳光洒进房间，[推进]"}],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9"
  }'

2. 图生视频（首帧）

图片作为视频起始画面；ratio 由图片决定（恒为 adaptive，可不传）：

curl http://localhost:8000/v1/cap/video/v2/video_generation \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "一只橘猫在窗台上伸懒腰，[推进]"},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}, "role": "first_frame"}
    ],
    "resolution": "768P",
    "duration": 6
  }'

3. 首尾帧视频

同时指定开始与结束画面（first_frame + last_frame），模型生成中间过渡：

curl http://localhost:8000/v1/cap/video/v2/video_generation \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "猫咪从窗台轻盈跳到沙发上"},
      {"type": "image_url", "image_url": {"url": "https://example.com/start.jpg"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/end.jpg"}, "role": "last_frame"}
    ],
    "resolution": "768P",
    "duration": 6
  }'

4. 多参视频（图片 + 声音 + 视频参数）

多模态参考生视频：参考图定角色/风格（最多 9 张）+ 参考视频定动作（最多 3 段）+ 参考音频定声音（最多 3 段），按需组合：

curl http://localhost:8000/v1/cap/video/v2/video_generation \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "宇航员在月球表面漫步，背景是浩瀚星空"},
      {"type": "image_url", "image_url": {"url": "https://example.com/astronaut.jpg"}, "role": "reference_image"},
      {"type": "image_url", "image_url": {"url": "https://example.com/style.jpg"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/walk.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/space.mp3"}, "role": "reference_audio"}
    ],
    "resolution": "2K",
    "duration": 8,
    "ratio": "16:9"
  }'

5. 视频编辑

把待编辑视频作为 reference_video 传入，用文本描述修改需求（换风格、换背景、改动作、加特效等）；可同时传 reference_image 指定新形象、reference_audio 指定配音：

curl http://localhost:8000/v1/cap/video/v2/video_generation \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "把画面变成赛博朋克风格，霓虹灯光，雨夜氛围"},
      {"type": "video_url", "video_url": {"url": "https://example.com/source.mp4"}, "role": "reference_video"}
    ],
    "resolution": "768P",
    "duration": 6
  }'

6. 本地文件直接上传（multipart/form-data）

除 JSON 外，视频接口也接受 multipart/form-data：表单字段与文件同一请求发出，文件值用 @本地路径，平台自动转存并生成 URL 发给上游，平台不设文件大小限制（仅网关本身的请求体上限）。字段名与 JSON content 角色的对应关系：

  • prompt 或 text → 文本项
  • first_frame / last_frame → 首帧 / 尾帧图片
  • image（或 reference_image）→ 参考图，可重复传多张
  • video（或 reference_video）→ 参考视频，可重复传多段
  • audio（或 reference_audio）→ 参考音频，可重复传多段
  • 其余字段（model / resolution / duration / ratio 等）原样作为顶层参数

图生视频（本地首帧图）：

curl http://localhost:8000/v1/cap/video/v2/video_generation \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "model=MiniMax-H3" \
  -F "prompt=一只橘猫在窗台上伸懒腰，[推进]" \
  -F "first_frame=@/Users/me/cat.jpg" \
  -F "resolution=768P" \
  -F "duration=6"

多参视频（本地参考图 + 参考视频 + 参考音频混合，也可与 URL 混用）：

curl http://localhost:8000/v1/cap/video/v2/video_generation \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "model=MiniMax-H3" \
  -F "prompt=宇航员在月球表面漫步，背景是浩瀚星空" \
  -F "image=@/Users/me/astronaut.jpg" \
  -F "image=https://example.com/style.jpg" \
  -F "video=@/Users/me/walk.mp4" \
  -F "audio=@/Users/me/space.mp3" \
  -F "resolution=2K" \
  -F "duration=8" \
  -F "ratio=16:9"

7. 轮询任务

curl http://localhost:8000/v1/cap/video/v2/query/video_generation/424010985738629 \
  -H "Authorization: Bearer sk-tg-你的密钥"

建议每 10 秒轮询一次。task.status 为 succeeded 时，task.content.url 即为成片下载地址。

参数与限制速查

  • model（必填）：视频生成模型；可选项见上方“模型可选项”，实时完整列表通过 GET/v1/models?category=video 获取
  • content[].type：text / image_url / video_url / audio_url
  • content[].role：first_frame / last_frame / reference_image / reference_video / reference_audio
  • resolution：480P / 768P / 2K（视模型而定）；duration：秒数
  • ratio：文生必填（21:9/16:9/4:3/1:1/3:4/9:16）；图生由图片决定；多参可选默认 adaptive
  • 参考数量上限按所选模型配置并由平台强制校验（超限返回 400）：如 MiniMax-H3 为图片 ≤ 9 张、视频 ≤ 3 段（每段 2–15s、总 ≤ 15s）、音频 ≤ 3 段；本地文件上传仅受网关请求体上限约束（大文件建议走 multipart 直传或公网 URL，勿用 Base64）
  • 图生与多参互斥：content 中出现 reference_* 就不能再用 first_frame/last_frame
  • 素材要求：图片 JPG/PNG/WEBP ≤ 30MB（256–5760px，宽高比 0.4–2.5）；视频 MP4/MOV（H.264/H.265）≤ 50MB；音频 WAV/MP3 ≤ 15MB
  • callback_url：可选，任务状态变更时回调通知

语音合成

本平台通过统一的能力路由 POST/v1/cap/speech/{上游路径} 接入两家语音供应商，按 model（MiniMax 系列）或 model_id（ElevenLabs 系列）前缀自动分派。返回为音频二进制流或 JSON 包装音频，直接透传上游。

1. MiniMax TTS

POST/v1/cap/speech/v1/t2a_v2 — 返回 JSON，音频在 data.audio（hex 编码），字符用量在 extra_info.usage_characters。

curl http://localhost:8000/v1/cap/speech/v1/t2a_v2 \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "text": "你好，欢迎使用 TokenGet。",
    "voice_setting": {
      "voice_id": "female-shaonv",
      "speed": 1,
      "vol": 1,
      "pitch": 0,
      "emotion": "happy"
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1
    }
  }'

MiniMax 模型可选项

  • speech-2.8-hd / speech-2.8-turbo
  • speech-2.6-hd / speech-2.6-turbo
  • speech-02-hd / speech-02-turbo
  • speech-01-hd / speech-01-turbo

MiniMax 参数说明

  • model（必填）：从上方可选项中选择
  • text（必填）：要合成的文本，单条长度受模型限制（通常 ≤ 10000 字符）
  • voice_setting（必填）：
    • voice_id：音色 ID，如 female-shaonv、male-qnqingse 等（以 MiniMax 官方更新为准）
    • speed：语速，默认 1，建议范围 0.5–2.0
    • vol：音量，默认 1，建议范围 0–10
    • pitch：音调，默认 0，建议范围 -12–12
    • emotion：情绪，如 happy / sad / neutral 等（可选，模型支持时生效）
  • audio_setting（必填）：
    • sample_rate：采样率，可选 16000 / 24000 / 32000 / 44100 / 48000
    • bitrate：码率，如 64000 / 128000 / 192000
    • format：输出格式，mp3 / wav / pcm / ogg
    • channel：声道数，1（单声道）或 2（立体声）
  • 计费：按请求文本字符数 × 1.5 系数扣积分；失败请求不计费

2. ElevenLabs TTS

POST/v1/cap/speech/v1/text-to-speech/{voice_id} — 直接返回 audio/mpeg 二进制音频。

curl http://localhost:8000/v1/cap/speech/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -o speech.mp3 \
  -d '{
    "model_id": "eleven_multilingual_v2",
    "text": "Hello, welcome to TokenGet.",
    "voice_settings": {
      "stability": 0.5,
      "similarity_boost": 0.75,
      "style": 0.0,
      "use_speaker_boost": true
    }
  }'

ElevenLabs 模型可选项

  • eleven_v3（质量最高，支持多语言）
  • eleven_multilingual_v2 / eleven_multilingual_v1
  • eleven_flash_v2_5 / eleven_flash_v2（低延迟）
  • eleven_turbo_v2_5 / eleven_turbo_v2
  • eleven_monolingual_v1

ElevenLabs 参数说明

  • model_id（必填）：从上方可选项中选择
  • text（必填）：要合成的文本
  • voice_id（路径参数）：目标音色 ID，如 JBFqnCBsd6RMkjVDRZzb；可通过上游官方接口 /v1/voices 获取
  • voice_settings（可选）：
    • stability：稳定性，0–1
    • similarity_boost：相似度增强，0–1
    • style：风格强度，0–1（部分模型支持）
    • use_speaker_boost：布尔值
  • pronunciation_dictionary_locators / seed / previous_text / next_text：可选高级参数（上游支持时透传）
  • 计费：按请求文本字符数 × 1.5 系数扣积分；失败请求不计费

3. 其他 ElevenLabs 能力

通过 /v1/cap/speech/v1/... 直接透传，参数与官方一致：

  • POST/v1/cap/speech/v1/text-to-voice/create-previews — 按文本描述生成预览音色（text 需 ≥ 100 字符）
  • POST/v1/cap/speech/v1/text-to-voice/create-voice-from-preview — 将预览音色保存为永久音色
  • POST/v1/cap/speech/v1/sound-generation — 音效生成
  • POST/v1/cap/speech/v1/voice_clone / POST/v1/cap/speech/v1/files/upload / POST/v1/cap/speech/v1/voices/add — 自定义音色相关（按上游官方 API 传参）

语音通用说明

  • 当前仅支持语音合成（TTS），暂未接入语音识别（STT）与音乐生成
  • 模型可选项以 GET/v1/models?category=speech 实时返回为准；未列出的 model/model_id 会路由失败
  • 请求体大小受 nginx 限制（1000MB）

文件接口

用户文件默认保存 2 天（管理员可按用户调整）。文件接口使用登录后的 JWT 认证。

  • POST/api/files — multipart 上传，返回 file_id
  • GET/api/files — 文件列表
  • GET/api/files/{file_id} — 下载
  • DELETE/api/files/{file_id} — 删除
TOKEN=<登录后的JWT>
# 上传
curl http://localhost:8000/api/files -H "Authorization: Bearer $TOKEN" -F "file=@photo.jpg"
# 列表
curl http://localhost:8000/api/files -H "Authorization: Bearer $TOKEN"
# 下载
curl http://localhost:8000/api/files/<file_id> -H "Authorization: Bearer $TOKEN" -o photo.jpg
# 删除
curl -X DELETE http://localhost:8000/api/files/<file_id> -H "Authorization: Bearer $TOKEN"

参数说明

  • file（上传必填）：multipart 文件字段；无格式限制，大小仅受 nginx 限制（1000MB）
  • purpose（可选）：文件用途标签，如 general / fine-tune / relay；不传默认 general
  • page / page_size（列表可选）：分页，默认第 1 页，每页 20 条，最大 100 条
  • 文件默认保留 2 天；管理员可通过 PATCH/api/admin/users/{id} 调整 file_retention_days

计费说明

  • 按调用量计费：每次成功调用按实际用量扣减积分，明细可在控制台「积分流水 / 调用记录」查询。
  • 失败的请求（HTTP ≥ 400）不计费。
  • 余额不足（≤ 0）时请求会被拒绝（HTTP 402），充值后立即恢复。
  • 新用户注册即送体验额度，可直接开始调用。

记录查询

  • GET/api/credits/balance — 当前余额
  • GET/api/credits/transactions?type=consume&page=1 — 积分流水（充值/消费/授予）
  • GET/api/calls?category=llm&page=1 — API 调用记录（默认保留 2 天）
TOKEN=<登录后的JWT>
curl http://localhost:8000/api/credits/balance -H "Authorization: Bearer $TOKEN"
curl "http://localhost:8000/api/credits/transactions?type=consume&page=1" -H "Authorization: Bearer $TOKEN"
curl "http://localhost:8000/api/calls?category=llm&page=1" -H "Authorization: Bearer $TOKEN"