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）

模型列表字段

调用 GET/v1/models 时，每个模型对象除 id / display_name / category / price_display / sale_price_display 外，还包含：

  • description：模型说明，含【输入参数】【适用场景】【模型说明】【版本差异】等信息
  • capabilities：能力对象，如 {"vision": true}（保留字段）
  • supports_image：是否支持图片输入
  • supports_audio：是否支持音频输入
  • supports_video：是否支持视频输入

多模态输入请以 image_url / audio_url / video_url 形式放在 messages 数组中；当前模型不支持对应输入类型时，平台将按规则自动在同类可用模型中选择最低价的支持模型进行替换，并通过响应头 X-Switched-Model 返回实际使用的模型名。

图片生成

图片能力统一入口为 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 — 历史列表
  • GET/v1/cap/tasks/{task_id} — 查询能力路由异步任务状态及结果（返回 task_id 时使用）

模型可选项

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

不同模型的返回形式由平台统一处理：本身已提供异步任务标识的模型返回 {"uuid": "..."}，需轮询 /v1/cap/image/history/{uuid} 获取结果；上游为同步返回的模型由网关自动包装为异步任务，返回 {"task_id": "..."}，需调用 GET /v1/cap/tasks/{task_id} 获取结果 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 秒轮询一次。

异步任务包装

图片能力路由会在网关层自动完成异步任务封装：若上游图片接口为同步返回，平台会自动将其包装为任务，下游仍按原有方式调用，无需关心上游实现差异。调用成功后将返回任务标识 {"task_id": "..."}：

curl http://localhost:8000/v1/cap/image/generate_image \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "prompt=a cute cat" \
  -F "model=你的生图模型"

拿到 task_id 后，通过 GET/v1/cap/tasks/{task_id} 查询结果：

curl http://localhost:8000/v1/cap/tasks/task-xxx \
  -H "Authorization: Bearer sk-tg-你的密钥"

返回示例：

{
  "task_id": "task-...",
  "status": "completed",
  "category": "image",
  "result_urls": ["https://..."],
  "upstream_response": { ... },
  "error": null,
  "created_at": "...",
  "completed_at": "..."
}

status 为 completed 时，图片 URL 在 result_urls 数组中；若上游调用失败则 status 为 failed，error 字段携带失败原因。该封装由 TokenGet 自动处理，下游接口路径与调用方式保持不变。

OpenAI 兼容图片生成

除能力路由外，平台还提供 OpenAI 兼容端点 POST/v1/images/generations。调用方用 JSON 传参，网关自动把请求路由到对应上游；若上游原生协议为 multipart/form-data，网关会在后台自动完成协议转换。

curl http://localhost:8000/v1/images/generations \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "a cute cat on a windowsill",
    "aspect_ratio": "1:1"
  }'

也支持以 multipart/form-data 直接调用，字段与上游原生接口一致：

curl http://localhost:8000/v1/images/generations \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "model=grok-imagine-2.0" \
  -F "prompt=a futuristic city at night" \
  -F "aspect_ratio=16:9" \
  -F "image=@/Users/me/ref.jpg"

可用模型请通过 GET/v1/models?category=image 实时获取，例如 gpt-image-1 / gpt-image-1.5 / grok-imagine-2.0 / nana-banana / nana-banana-pro 等。返回形式由平台统一处理：若返回 {"uuid":"..."}，需轮询 /v1/cap/image/history/{uuid}；若返回 {"task_id":"..."}，需调用 GET /v1/cap/tasks/{task_id} 获取结果。

视频生成

视频能力统一入口为 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：可选，任务状态变更时回调通知

OpenAI 兼容视频生成

平台同时提供 OpenAI 兼容端点 POST/v1/videos。调用方用 JSON 传参，网关自动路由到对应上游；若上游原生协议为 multipart/form-data（如 SnapGen），网关会在后台自动完成协议转换。

curl http://localhost:8000/v1/videos \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0-mini",
    "prompt": "an astronaut walking on the moon, cinematic lighting",
    "ratio": "16:9",
    "duration": 6
  }'

也支持以 multipart/form-data 直接调用：

curl http://localhost:8000/v1/videos \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -F "model=grok-imagine-video" \
  -F "prompt=a robot dancing in neon lights" \
  -F "ratio=9:16" \
  -F "duration=5" \
  -F "first_frame=@/Users/me/start.jpg"

可用模型请通过 GET/v1/models?category=video 实时获取，例如 seedance-2-0-mini / seedance-2.0-fast / grok-imagine-video 等。返回格式遵循上游原生响应（SnapGen 返回任务 ID，需轮询对应历史接口获取成片 URL）。

GoAnyAI 供应商与分组

GoAnyAI 已作为独立供应商接入。其模型按官方 marketplace 的分组拆分为多个对外模型名，格式为 {模型名}--{分组名}；不传分组时可直接使用基础模型名，系统会路由到默认（最低价）分组。

  • 基础模型名（默认分组）：claude-fable-5 / gpt-image-2 / grok-imagine-video 等
  • 指定分组：claude-fable-5--AWS-Claude-分组 / gpt-image-2--特价--image-1k 等
  • 价格来自 GoAnyAI 官方 marketplace，按人民币成本计价，再乘以平台售价系数后向下游展示

调用方式与普通模型一致，例如指定分组生成图片：

curl http://localhost:8000/v1/images/generations \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2--特价--image-1k",
    "prompt": "a cute cat on a windowsill"
  }'

或指定分组进行对话：

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-tg-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-5--kiro-Claude",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

管理员可在后台「上游供应商」页看到 goanyai，点击「同步 GoAnyAI」即可一键拉取最新模型、分组与价格。

语音合成

本平台通过统一的能力路由 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"