接口文档

1. 接入前准备

获取 API Key

登录后进入 API 接入 页面创建 Key。默认以 bet_ 开头、总长 44 位；后台可修改开头与总长度，以站点设置为准。只在创建时显示一次，服务端仅保存 SHA-256。

Base URL

https://tts.blackegg.cn

鉴权方式

兼容层使用本站 bet_ Key，不是 OpenAI / Fish / Google 官方 Key；请勿填各厂商的官方密钥。

通用限制

• 每个 Key 每分钟最多 30 次（后台可调）。
• 单条文本最多 500 字（后台可调）。
• 只输出 audio/mpeg（MP3）；请求其他格式会返回 400。
• 未传音色时按「个人默认音色 > 站点默认音色 > fish 默认」回落。
• 开启计费后按模型与字数扣余额，余额不足返回 402。

2. 接口总览

所有接口都支持 OPTIONS 预检，返回 204，并带 CORS 头。

3. 本站原生接口

POST/api/v1/tts

请求参数（JSON）

响应

默认返回 JSON：

{"ok":true,"id":12,"url":"/audio?id=12","bytes":23456,"model":"s2.1-pro-free"}

请求头带 Accept: audio/mpeg 时直接返回 MP3 二进制。

示例

curl -X POST https://tts.blackegg.cn/api/v1/tts \
  -H "Authorization: Bearer bet_你的KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"你好，世界","voice":"示例音色","model":"s2.1-pro-free"}'

4. OpenAI TTS 兼容

POST/v1/audio/speech

可直接把 OpenAI SDK 的 base_url 指向本站 https://tts.blackegg.cn/v1。

请求参数（JSON）

响应

成功返回 200，Content-Type: audio/mpeg，响应体为 MP3 字节；附带 X-Gen-Id 便于排查。

示例（curl）

curl -X POST https://tts.blackegg.cn/v1/audio/speech \
  -H "Authorization: Bearer bet_你的KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"s2.1-pro-free","voice":"示例音色","input":"你好，世界","response_format":"mp3"}' \
  --output hello.mp3

示例（OpenAI Python SDK）

from openai import OpenAI

client = OpenAI(api_key="bet_你的KEY", base_url="https://tts.blackegg.cn/v1")
resp = client.audio.speech.create(
    model="s2.1-pro-free",
    voice="示例音色",
    input="你好，世界",
)
resp.stream_to_file("hello.mp3")

5. Fish Audio 兼容

POST/v1/tts

字段与 fish.audio 的 /v1/tts 对齐，可把 Fish 客户端的 Base URL 指向本站；鉴权仍用本站 bet_ Key。

请求参数（JSON）

响应

成功返回 200，响应体为 MP3 字节，Content-Type: audio/mpeg。

示例

curl -X POST https://tts.blackegg.cn/v1/tts \
  -H "Authorization: Bearer bet_你的KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"你好，世界","reference_id":"YOUR_REFERENCE_ID","format":"mp3"}' \
  --output hello.mp3

错误格式：{"detail":"错误原因"}，HTTP 状态码与原生接口一致。

6. Gemini TTS 兼容

POST/v1beta/models/{model}:generateContent

接受 Gemini generateContent 的请求结构，返回 candidates[0].content.parts[0].inlineData。路径里的模型名只用于兼容，实际使用站点默认模型。

请求参数（JSON）

响应

{
  "candidates": [{
    "content": {
      "parts": [{
        "inlineData": {"mimeType": "audio/mpeg", "data": "<base64 MP3>"}
      }],
      "role": "model"
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "modelVersion": "s2.1-pro-free",
  "usageMetadata": {"promptTokenCount": 6, "candidatesTokenCount": 0, "totalTokenCount": 6}
}

示例（curl）

curl -X POST "https://tts.blackegg.cn/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
  -H "x-goog-api-key: bet_你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "你好，世界"}]}],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "示例音色"}}}
    }
  }'

也支持 ?key=bet_你的KEY 和 Authorization: Bearer 两种鉴权。

7. 音色与模型

查询音色

curl https://tts.blackegg.cn/api/v1/voices -H "Authorization: Bearer bet_你的KEY"

返回：

{"ok":true,"count":2,"voices":[
  {"id":3,"name":"示例音色","ref_id":"YOUR_REF_A","model":"","tags":"","remark":""},
  {"id":4,"name":"示例音色 B","ref_id":"YOUR_REF_B","model":"","tags":"","remark":""}
]}

音色取值

• 推荐使用 ref_id，稳定且不受改名影响。
• 也可用音色库 id 或 name（名称需唯一且启用）。
• 默认音色在「个人设置 → 默认音色」和「后台 → 站点设置 → 站点默认音色」配置。

本站可用模型