ttqq 网关使用文档

2026-10-06 集群方案：裸 qwen3.8:27b / qwen3.6:35b-a3b 零注入。TTS 演播 clavue-tts release clavue-tts-r6-wave3-20261003（十声）见 ttkk 有声小说。作词、caption、TTS 稿打裸名 + 自己的 system。别名手册 · 创作线 · ttkk 总览。

2026-10-05 文生图：集群 clavue-img / z-image-turbo 默认返回 WebP（output_format 省略或 webp）。要 JPEG 传 jpeg/jpg，素材图传 png。与 codex 的 gpt-image-2（默认 PNG、走上游透传）不是同一套默认值——见 7.5 节 与 image.html。

基于 new-api 的多平台 LLM 网关。统一入口 https://ttqq.inping.com，通过路径前缀切换平台（codex / grok / windsurf / sora / claude / gemini …），同时兼容 OpenAI Chat Completions、Anthropic Messages、Gemini 原生、OpenAI Responses 四种协议。

1. 概述#

• 多平台：codex / grok / windsurf / sora / claude / gemini 等多家上游统一收敛。
• 多协议：同一域名下，不同路径暴露不同协议——OpenAI 兼容、Anthropic Messages、Gemini 原生、OpenAI Responses。
• 纯透传：codex / grok / windsurf 等第三方平台请求体原样转发。集群自有 model（clavue-img、qwen3.8:27b 等）会按渠道映射打到 ttkk.inping.com，生图另有 hop（如强制 b64_json、尺寸白名单）——见 7.5 节。

2. 路径与平台前缀#

所有 API 路径有两种等价写法：

https://ttqq.inping.com/v1/...                # 用令牌默认平台
https://ttqq.inping.com/{platform}/v1/...     # 显式指定平台

常见平台前缀：

不带前缀的请求（如 /v1/chat/completions）由 new-api 按令牌分组和模型映射自动选渠道；带前缀则锁定到对应平台。

3. 认证#

Authorization: Bearer YOUR_API_KEY

Anthropic Messages 协议同时接受：

X-Api-Key: YOUR_API_KEY
anthropic-version: 2023-06-01

Gemini 原生协议还接受：

X-Goog-Api-Key: YOUR_API_KEY
# 或 query 参数
?key=YOUR_API_KEY

令牌从 控制台 申请，每个令牌可绑定模型白名单、分组、配额。

4. 协议总览#

5. 平台与模型清单#

下列是当前实际在用的平台与模型。可用性以你令牌的分组为准。

其它平台（claude / sora / gemini / cursor / kiro / copilot / flow / antigravity / vertex）在网关侧已开通。模型名以 官方文档 各平台子页为准。

6. OpenAI Chat Completions#

6.1 基础调用

curl https://ttqq.inping.com/v1/chat/completions \
  -H "Authorization: Bearer $YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "system", "content": "你是一个简明助手。" },
      { "role": "user", "content": "用一句话解释 P=NP 问题。" }
    ],
    "stream": false
  }'

from openai import OpenAI
client = OpenAI(base_url="https://ttqq.inping.com/v1", api_key="YOUR_KEY")
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hi"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://ttqq.inping.com/v1",
  apiKey: process.env.YOUR_KEY,
});
const resp = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Hi" }],
});
console.log(resp.choices[0].message.content);

6.2 选择平台与模型

三种典型组合：

# Codex 平台用 gpt-5.5
POST /codex/v1/chat/completions   { "model": "gpt-5.5", ... }

# Grok 平台
POST /grok/v1/chat/completions    { "model": "grok-420-fast", ... }

# Windsurf 平台用 Claude（chat 协议形式）
POST /windsurf/v1/chat/completions { "model": "claude-opus-4-7-max", ... }

7. 图像接口#

同一 URL 下有两类 model：codex 的 gpt-image-2（本节 7.1–7.4，请求原样透传到 OpenAI 上游，默认 PNG）与集群的 clavue-img / z-image-turbo（7.5 节，走 ttkk 后端，默认 WebP）。选错 model 会得到完全不同的默认编码与超时行为。

7.1 第三方文生图 — gpt-image-2（POST /v1/images/generations）

使用 OpenAI 标准 images 接口，请求原样转发到 codex 上游。图生图打 /v1/images/edits，见 7.2。

curl https://ttqq.inping.com/v1/images/generations \
  -H "Authorization: Bearer $YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a wooden table, studio light",
    "size": "1024x1024"
  }'

常用参数（透传到上游 OpenAI）

input_fidelity 不要传——gpt-image-2 内部固定使用高保真，传了会被上游报错。

7.2 图生图 — POST /v1/images/edits

带 1 张或多张参考图（垫图）走 edits 端点。

方式 A：JSON + URL/base64

curl https://ttqq.inping.com/v1/images/edits \
  -H "Authorization: Bearer $YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把帽子改成红色",
    "images": [
      { "image_url": "https://example.com/portrait.png" }
    ],
    "size": "1024x1024"
  }'

方式 B：multipart 上传本地文件（OpenAI 官方推荐）

curl https://ttqq.inping.com/v1/images/edits \
  -H "Authorization: Bearer $YOUR_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=把帽子改成红色" \
  -F "image[]=@/path/to/portrait.png" \
  -F "size=1024x1024"

edits 额外字段

7.3 高分辨率（2K / 4K）

gpt-image-2 支持任意符合下述约束的分辨率：

• 最长边 ≤ 3840px
• 两边都是 16 的倍数
• 长短边比 ≤ 3:1
• 总像素 655,360 ~ 8,294,400

常用尺寸：

真 4K 方图 4096x4096 不允许（最长边超 3840）。> 3.69M 像素的输出被 OpenAI 标记为实验性。

7.4 流式 partial 图（Responses API tool）

需要"边生成边收阶段图"的体验，请用 第 9 节 Responses API 的 image_generation tool。原生 /v1/images/generations 当前没有 partial 流式输出。

7.5 集群文生图 — clavue-img / z-image-turbo#

POST /v1/images/generations，model 用 clavue-img（产品名）或 z-image-turbo（引擎名）。ttqq 与 https://ttkk.inping.com/v1 使用相同 JSON 字段；官方会员入口 https://api.clavue.com/v1 用 aspect_ratio 代替部分 size 写法，同样支持 output_format。

公网 hop 对 clavue-img 会强制 response_format=b64_json。尺寸白名单：1024×1024 / 768×1344 / 1344×768（写 512 会被升到 1024）。不传 output_format 时默认 WebP（quality 80）。jpeg / jpg 返回 JPEG（quality 85），png 返回无损 PNG（素材图）。响应里的 output_format 回显实际编码；b64_json 字节与该字段一致，不要默认按 PNG 解码。非法 output_format 返回 400。换格式不改变 GPU 生成时间；客户端超时仍 ≥ 120 s。

curl -sS https://ttqq.inping.com/v1/images/generations \
  -H "Authorization: Bearer $CLAVUE_KEY" -H "Content-Type: application/json" \
  -d '{"model":"clavue-img","prompt":"清晨窗边，暖光，胶片感","size":"1024x1024","output_format":"webp"}'

改图（qwen-image-edit、clavue-album 等）走 /v1/images/edits，约 75 s/张，超时 ≥ 300 s。完整模型表见 image.html 与 ttkk 镜像。

8. Anthropic Messages（Claude / Windsurf）#

Claude 系模型（含 Windsurf 通道的 claude-opus-4-7-*）建议用此协议。请求/响应格式与 Anthropic 官方一致。

curl https://ttqq.inping.com/v1/messages \
  -H "x-api-key: $YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-7-max",
    "max_tokens": 1024,
    "system": "You are a senior engineer.",
    "messages": [
      { "role": "user", "content": "review this code: ..." }
    ]
  }'

Anthropic SDK 直接换 base URL 即可：

from anthropic import Anthropic
client = Anthropic(
    base_url="https://ttqq.inping.com",
    api_key="YOUR_KEY",
)
msg = client.messages.create(
    model="claude-opus-4-7-max",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hi"}],
)
print(msg.content[0].text)

8.1 Windsurf 三档质量怎么选

三档的认知质量由模型层面决定，路由不会自动升降档。请在客户端按任务难度自行选模型。

8.2 也可以用 chat completions 协议调 Claude

如果你的客户端不想换协议，把 claude-opus-4-7-max 直接放进 /v1/chat/completions 也行——网关会做格式转换。但原生 /v1/messages 更稳，特别是涉及 tool_use、system 数组、cache_control 时。

9. OpenAI Responses#

OpenAI 新一代推理协议（reasoning + 多步工具）。在 codex 平台上对 gpt-5.5 等支持的模型可用：

curl https://ttqq.inping.com/v1/responses \
  -H "Authorization: Bearer $YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "证明：根号 2 是无理数。",
    "reasoning": { "effort": "medium", "summary": "auto" },
    "stream": false
  }'

9.1 image_generation tool（流式 partial 图）

在 Responses API 上挂 image_generation 工具，可以让 mainline 模型边推理边生成图，并通过 SSE 收到阶段性 partial 图（OpenAI 官方推荐的"流式画图"路径）。

import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI({
  baseURL: "https://ttqq.inping.com/v1",
  apiKey: process.env.YOUR_KEY,
});

const stream = await openai.responses.create({
  model: "gpt-5.5",
  input: "Draw a gorgeous river of white owl feathers in a winter landscape",
  stream: true,
  tools: [{ type: "image_generation", partial_images: 2 }],
});

for await (const event of stream) {
  if (event.type === "response.image_generation_call.partial_image") {
    const idx = event.partial_image_index;
    const buf = Buffer.from(event.partial_image_b64, "base64");
    fs.writeFileSync(`river${idx}.png`, buf);
  }
}

SSE 事件类型：response.image_generation_call.partial_image（payload 含 partial_image_index 和 partial_image_b64）。

10. 视频接口（Sora / Flow）#

视频生成本质上是异步任务——上游需要 30 秒到几分钟，必须用提交 + 查询的两步流程。

10.1 提交任务

POST /v1/videos
{
  "model": "sora-2",
  "prompt": "a corgi running on the beach at sunset",
  "input_reference": "https://example.com/style-ref.png"   // 可选
}
# 返回 { "id": "", "status": "<状态>", ... }

10.2 查询任务状态

GET /v1/videos/{task_id}            # 查询元信息
GET /v1/videos/{task_id}?detail=true # 含详细元数据
GET /v1/videos/{task_id}/content     # 完成后下载原始视频

10.3 Sora 角色与替身（cameos）

POST   /sora/v1/characters           # 创建非真人角色
GET    /sora/v1/cameos/session       # 获取真人替身的口播口令
POST   /sora/v1/cameos               # 上传真人替身（multipart）
GET    /sora/v1/cameos/{role_id}     # 查询
PUT    /sora/v1/cameos/{role_id}     # 更新（昵称、头像）
DELETE /sora/v1/cameos/{role_id}     # 删除

11. 参数完整说明#

12. 响应格式#

12.1 Chat Completions

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1714000000,
  "model": "gpt-5.5",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 28, "total_tokens": 40 }
}

12.2 原生 Images

{ "created": 1714000000, "data": [{ "b64_json": "..." }] }
{ "created": 1714000000, "data": [{ "url": "https://..." }] }

12.3 Anthropic Messages

{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-7-max",
  "content": [{ "type": "text", "text": "..." }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 12, "output_tokens": 28 }
}

13. 流式#

所有 chat completions / messages / responses 端点都支持 stream: true。SSE 输出，data: ...\n\n 分块，最后 data: [DONE]。

图像生成原生 /v1/images/generations 不支持 stream。需要"边生成边收"的体验，请用 Responses API + image_generation tool 的 partial_images。

14. 异步任务#

14.1 视频

视频接口本身就是异步：POST /v1/videos 返回 task_id，GET /v1/videos/{task_id} 轮询，完成后 GET /v1/videos/{task_id}/content 取视频文件。

14.2 图像

原生 /v1/images/generations 和 /v1/images/edits 接受 "async": true 或 ?async=true，行为由上游决定。

15. 配额与限频#

• 每日配额：默认 86,400 次/日（即均摊 1 QPS）。控制台可查实时使用率。
• 按平台计：codex / grok / windsurf 各自分别记账。
• 触发限频：返回 429，建议带指数退避重试。
• 提升上限：联系管理员或在控制台开通"附加功能权限"。

上游计费以"对话次数"为基本单位，每种端点（chat / responses / messages / images / videos）按各自规则记账。

16. 错误码#

17. 完整示例#

17.1 Codex / gpt-5.5 — Python（OpenAI SDK）

from openai import OpenAI
client = OpenAI(base_url="https://ttqq.inping.com/v1", api_key="YOUR_KEY")
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "Be concise."},
        {"role": "user", "content": "Pros and cons of B-tree vs LSM-tree?"},
    ],
    stream=True,
)
for chunk in resp:
    if delta := chunk.choices[0].delta.content:
        print(delta, end="", flush=True)

17.2 Grok — Node.js

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://ttqq.inping.com/grok/v1",
  apiKey: process.env.YOUR_KEY,
});
const resp = await client.chat.completions.create({
  model: "grok-420-fast",
  messages: [{ role: "user", content: "Three weird startup ideas" }],
});
console.log(resp.choices[0].message.content);

17.3 Windsurf / Claude — Python（Anthropic SDK）

from anthropic import Anthropic
client = Anthropic(
    base_url="https://ttqq.inping.com/windsurf",
    api_key="YOUR_KEY",
)
msg = client.messages.create(
    model="claude-opus-4-7-max",
    max_tokens=2048,
    system="You are a senior code reviewer.",
    messages=[{"role": "user", "content": "review the diff in /tmp/x.diff"}],
)
print(msg.content[0].text)

17.4 Codex 图像 — Node.js（OpenAI SDK 标准用法）

import OpenAI from "openai";
import fs from "fs/promises";

const client = new OpenAI({
  baseURL: "https://ttqq.inping.com/v1",
  apiKey: process.env.YOUR_KEY,
});

// 文生图
async function textToImage(prompt) {
  const resp = await client.images.generate({
    model: "gpt-image-2",
    prompt,
    size: "1024x1024",
  });
  const b64 = resp.data[0].b64_json;
  await fs.writeFile("out.png", Buffer.from(b64, "base64"));
}

// 图生图（multipart 上传本地文件）
async function imageToImage(prompt, refPath) {
  const resp = await client.images.edit({
    model: "gpt-image-2",
    prompt,
    image: await fs.readFile(refPath),  // SDK 自动 multipart
    size: "1024x1024",
  });
  const b64 = resp.data[0].b64_json;
  await fs.writeFile("out.png", Buffer.from(b64, "base64"));
}

await textToImage("a red apple");
await imageToImage("把帽子改成红色", "./portrait.png");

17.5 Sora 视频 — cURL（提交 + 轮询 + 下载）

# 1. 提交
curl https://ttqq.inping.com/v1/videos \
  -H "Authorization: Bearer $YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "sora-2", "prompt": "a corgi running on a beach" }'
# 假设返回 {"id": "vid_abc123", "status": "queued"}

# 2. 轮询
while true; do
  s=$(curl -s https://ttqq.inping.com/v1/videos/vid_abc123 \
    -H "Authorization: Bearer $YOUR_KEY")
  echo "$s"
  echo "$s" | grep -q '"status":"succeeded"' && break
  sleep 5
done

# 3. 下载视频文件
curl https://ttqq.inping.com/v1/videos/vid_abc123/content \
  -H "Authorization: Bearer $YOUR_KEY" -o out.mp4

18. 常见问题#

Q1: 同一个令牌能调所有平台吗？

取决于令牌的"分组"和"模型白名单"。控制台可以一个令牌开多平台权限，也可以分别建专用令牌。

Q2: 不带 /{platform} 前缀和带前缀的区别？

不带前缀走 new-api 的渠道路由：按 model 名匹配可用渠道，自动选一个。带前缀则锁定到该平台的渠道——用于强制走特定上游、隔离故障、或上游有同名模型时区分。

Q3: 网关会修改我的请求或响应吗？

不会。所有 /v1/* 请求原样转发到上游 new-api / 各家平台，请求体、字段、headers 一字节不改。响应同样原样回传。不要把 model: "gpt-image-2" 直接打到 /v1/chat/completions 上指望网关帮你转——上游不会理解。

Q4: claude-opus-4-7-max/high/low 应该怎么选？

三档不是路由策略，是不同模型实例。max 默认；high 在质量与成本之间折中；low 用于高频低复杂度任务。详见第 8 节。

Q5: 504 / 超时排查思路？

三步：(1) 检查 model 拼写是否在第 5 节清单内；(2) 检查端点和模型是否匹配（图像模型不能打 chat 端点）；(3) 切换到无 /{platform} 前缀试一次，对比是否是渠道问题。

Q6: 怎么上传本地图片做图生图？

用原生 /v1/images/edits + multipart：-F "image[]=@/path/to/file.png"。OpenAI SDK 直接传 fs.readFileSync() 也可以。

Q7: 计费按什么维度？

按"对话次数"为基本单位，不同平台和模型有各自的倍率。控制台显示的是按平台的累计次数。

Q8: clavue-img 和 gpt-image-2 的 output_format 默认值一样吗？

不一样。gpt-image-2（codex 透传）默认 png。clavue-img / z-image-turbo（集群）默认 webp。同一 URL /v1/images/generations 下靠 model 区分；解码 b64_json 前先看响应里的 output_format 或文件魔数。详见 7.5 节。

19. 变更记录#

• 2026-10-09 — 语音识别：funasr、faster-whisper-medium、sensevoice 走 POST /v1/audio/transcriptions，同一 SenseVoice。说明见 ttkk asr.html。
• 2026-10-05 — 集群文生图默认 WebP；文档新增 7.5 clavue-img、image.html 与 ttkk 指引互链；区分 codex gpt-image-2 与集群模型的 output_format 默认值。
• 2026-05-08（v1.2） — 移除 chat ↔ images 协议适配层，全面回归"纯透传"。/v1/chat/completions 和 GET /v1/images/{task_id} 不再被网关拦截。补全 gpt-image-2 完整参数（含 2K/4K 尺寸、output_format、moderation 等）。新增 Responses API image_generation tool 流式 partial 用法。
• 2026-05-08（v1.1） — 多平台扩展：补充 codex / grok / windsurf 模型清单、Anthropic Messages、Responses、Sora 视频、配额说明。
• 2026-05-08（v1.0） — 文档首次上线（含 chat ↔ images 协议适配器，已于 v1.2 移除）。