API API 接入文档

客户接入说明

统一接口，接入主流大模型

一个 API Key 即可调用 Claude、GPT、Gemini、DeepSeek、GLM、Kimi、Qwen 等模型，覆盖文本、图片、视频与语音合成。 本文档面向技术接入方，以及会自动生成接入代码的 AI 助手，对每类模型只给出一种推荐调用方式以降低歧义。

基本信息

Base URL
https://api.example.com
鉴权方式
Bearer Key / x-api-key / x-goog-api-key
模型列表接口
GET /v1/models
  • 同一个 API Key 可访问当前账号下全部已开放模型。
  • 接入时请直接按本文档给出的方式调用对应模型。
  • 如果只想先验证 Key 是否可用，建议先调用 /v1/models。

快速连通性测试

返回 success: true 且能看到 data 数组，说明 Key 与平台链路正常。

curl "https://api.example.com/v1/models" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

模型清单

按协议归类如下。同类模型切换时通常只需替换 model 字段。

Anthropic Claude 文本
claude-haiku-4-5-20251001claude-opus-4-6 claude-opus-4-7claude-opus-4-8claude-sonnet-4-6
OpenAI GPT / DeepSeek / GLM / Kimi / Qwen
gpt-5.4gpt-5.5 DeepSeek-V4-FlashDeepSeek-V4-Pro glm-4.7glm-5GLM-5.1GLM-5V-Turbo Kimi-K2.6qwen3.6-flashqwen3.6-max-previewqwen3.6-plus
Gemini 文本
gemini-3-flash-previewgemini-3-pro-preview gemini-3.5-flashgemini-3.1-pro-preview
Gemini 图像
gemini-3-pro-image-previewgemini-3.1-flash-image-preview
OpenAI Images 图片生成
gpt-image-2
视频任务 Happyhorse 视频
happyhorse-1.0-t2vhappyhorse-1.0-i2v happyhorse-1.0-r2vhappyhorse-1.0-video-edit
视频任务 Seedance 视频
doubao-seedance-2-0-260128doubao-seedance-2-0-fast-260128
Audio Speech 语音合成
qwen3-tts-flashMiniMax/speech-2.8-turboMiniMax/speech-2.8-hd

Anthropic Claude 文本

接口：POST /v1/messages。鉴权头为 x-api-key，需带 anthropic-version。

curl "https://api.example.com/v1/messages" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "请用一句话介绍你自己"}
    ]
  }'
import requests

resp = requests.post(
    "https://api.example.com/v1/messages",
    headers={
        "x-api-key": "<YOUR_API_KEY>",
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
    },
    json={
        "model": "claude-sonnet-4-6",
        "max_tokens": 1024,
        "messages": [
            {"role": "user", "content": "请用一句话介绍你自己"}
        ],
    },
    timeout=120,
)

resp.raise_for_status()
print(resp.json()["content"][0]["text"])

OpenAI GPT / DeepSeek / GLM / Kimi / Qwen 文本

接口：POST /v1/chat/completions。切换同类模型时只需替换 model。

curl "https://api.example.com/v1/chat/completions" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "请用一句话介绍你自己"}
    ],
    "max_tokens": 512
  }'
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_API_KEY>",
    base_url="https://api.example.com/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "user", "content": "请用一句话介绍你自己"}
    ],
    max_tokens=512,
)

print(resp.choices[0].message.content)
部分推理模型会消耗较多输出 token。使用 DeepSeek-V4-Pro 等模型时，建议设置足够的 max_tokens。 切换到 DeepSeek-V4-Flash、GLM-5.1、Kimi-K2.6、qwen3.6-plus 等同类模型时，只需替换 model。

Gemini 文本 · 原生协议

接口：POST /v1beta/models/{model}:generateContent。鉴权头为 x-goog-api-key。

curl "https://api.example.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "请用一句话介绍你自己"}
        ]
      }
    ]
  }'
import requests

resp = requests.post(
    "https://api.example.com/v1beta/models/gemini-3.5-flash:generateContent",
    headers={
        "x-goog-api-key": "<YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "contents": [
            {
                "parts": [
                    {"text": "请用一句话介绍你自己"}
                ]
            }
        ]
    },
    timeout=120,
)

resp.raise_for_status()
print(resp.json()["candidates"][0]["content"]["parts"][0]["text"])

图片生成

OpenAI Images GPT 图片模型

接口：POST /v1/images/generations。返回的 base64 在 data[0].b64_json。

curl "https://api.example.com/v1/images/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "画一个极简红苹果图标",
    "size": "1024x1024"
  }'
import base64
import requests

resp = requests.post(
    "https://api.example.com/v1/images/generations",
    headers={
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "画一个极简红苹果图标",
        "size": "1024x1024",
    },
    timeout=180,
)

resp.raise_for_status()
image_b64 = resp.json()["data"][0]["b64_json"]

with open("output.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

Gemini 图片模型 · 原生协议

接口：POST /v1beta/models/{model}:generateContent。

curl "https://api.example.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "生成一张极简蓝色圆形图标，白色背景"}
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'
返回结构说明：图片 base64 返回在 candidates[0].content.parts[*].text 字段中， 不要按 Gemini 官方 inlineData.data 方式解析。需要保存图片时，取出对应 text 字段内容后自行做 base64 解码。

返回示例（伪结构）：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "<image_base64>"
          }
        ]
      }
    }
  ]
}

视频生成

Happyhorse 系列 · /v1/videos

视频生成是异步任务。创建任务后返回 id / task_id，需通过 GET /v1/videos/{task_id} 轮询结果。 素材图片 / 视频必须通过公网可访问 URL 提供。 
curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "input": {
      "prompt": "一匹白色小马在草原上奔跑，阳光明媚，电影感镜头"
    },
    "parameters": {
      "resolution": "720P",
      "duration": 5,
      "ratio": "16:9",
      "watermark": false
    }
  }'
# 图片必须通过公网可访问 URL 提供
curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-i2v",
    "input": {
      "prompt": "让图片中的人物自然挥手，背景保持稳定",
      "media": [
        {
          "type": "input_image",
          "url": "https://example.com/input.jpg"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "duration": 5,
      "watermark": false
    }
  }'
# 参考图片必须通过公网可访问 URL 提供
curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-r2v",
    "input": {
      "prompt": "[Image 1]中的人物向镜头挥手，保持人物特征一致",
      "media": [
        {
          "type": "reference_image",
          "url": "https://example.com/reference-1.jpg"
        },
        {
          "type": "reference_image",
          "url": "https://example.com/reference-2.jpg"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "duration": 3,
      "ratio": "16:9",
      "watermark": false
    }
  }'
# 输入视频必须通过公网可访问 URL 提供
# duration 放在顶层，用于计费用时；media.type 使用 video
curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "duration": 3,
    "input": {
      "prompt": "将视频调整为电影感暖色调，保持主体动作自然",
      "media": [
        {
          "type": "video",
          "url": "https://example.com/input.mp4"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "watermark": false,
      "audio_setting": "origin"
    }
  }'
curl "https://api.example.com/v1/videos/<task_id>" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

创建任务响应示例：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "model": "happyhorse-1.0-video-edit",
  "status": "queued",
  "created_at": 1779381684
}

任务完成响应示例（结果视频地址在 metadata.url）：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "model": "happyhorse-1.0-video-edit",
  "status": "completed",
  "progress": 100,
  "metadata": {
    "url": "https://example.com/generated-video.mp4"
  },
  "error": null
}
  • 状态包括 queued、in_progress、completed、failed、cancelled。
  • 素材 URL 必须公网可访问，应为图片或视频文件直链；不支持本地路径，不建议 base64，不要使用需登录 / Cookie / 内网访问的地址。

Seedance 2.0 · /v1/video/generations

字节豆包 Seedance 视频模型，使用独立端点 /v1/video/generations（与 Happyhorse 的 /v1/videos 不同），返回结构也不同。同样是异步任务：提交 → 轮询。

doubao-seedance-2-0-260128 · 标准版（画质更好） doubao-seedance-2-0-fast-260128 · 快速版（生成更快） 
curl "https://api.example.com/v1/video/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "一个中国男孩在挥舞一把宝剑",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 4,
    "generate_audio": false
  }'
curl "https://api.example.com/v1/video/generations/<task_id>" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

提交任务返回 task_id，状态为 queued：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued"
}

轮询：生成中为 IN_PROGRESS，完成为 SUCCESS，取 data.result_url 下载（链接有效期约 7 天）：

{
  "data": {
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://.../task.mp4?sign=..."
  }
}
参数类型说明
modelstring模型名，见上表
promptstring视频描述，中英文均可
resolutionstring480p / 720p / 1080p
ratiostring16:9 / 9:16 / 1:1
durationint时长（秒），建议 4–8
generate_audiobool是否生成背景音（默认 false）
建议每隔 30 秒轮询一次，最多等待约 10 分钟超时。4 秒视频标准版约 2–3 分钟、快速版约 1–2 分钟。

语音合成 TTS · /v1/audio/speech

以下模型统一使用该接口：qwen3-tts-flash、MiniMax/speech-2.8-turbo、MiniMax/speech-2.8-hd。返回音频二进制，需按文件流保存。

curl "https://api.example.com/v1/audio/speech" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-tts-flash",
    "input": "你好，这是一个测试。",
    "voice": "Cherry"
  }' \
  --output speech.wav
import requests

resp = requests.post(
    "https://api.example.com/v1/audio/speech",
    headers={
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen3-tts-flash",
        "input": "你好，这是一个测试。",
        "voice": "Cherry",
    },
    timeout=180,
)

resp.raise_for_status()
with open("speech.wav", "wb") as f:
    f.write(resp.content)
qwen3-tts-flash
voice：Cherry
MiniMax/speech-2.8-turbo
voice：male-qn-qingse
MiniMax/speech-2.8-hd
voice：male-qn-qingse
  • 可选参数 response_format：指定音频格式，例如 mp3。
  • 可选参数 speed：调整语速。

Claude thinking 使用说明

如需 Claude thinking，可在 Anthropic 接口里传入 thinking 参数。

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 8192
  },
  "messages": [
    {
      "role": "user",
      "content": "证明根号 2 是无理数，并写出完整步骤"
    }
  ]
}
  • claude-sonnet-4-6 可返回 thinking / signature。
  • claude-opus-4-7 如需使用 thinking，建议先单独验证业务请求。
  • 如果只是普通聊天，不需要传 thinking。

模型接入方式汇总

模型类型接入方式
ClaudeAnthropic /v1/messages
GPT / DeepSeek / GLM / Kimi / Qwen 文本OpenAI /v1/chat/completions
Gemini 文本Gemini 原生 POST /v1beta/models/{model}:generateContent
Gemini 图像相关模型Gemini 原生 POST /v1beta/models/{model}:generateContent
图片生成/v1/images/generations
视频生成/v1/videos
TTS/v1/audio/speech

接入注意事项

  1. GET /v1/models 返回的是当前 Key 可见的模型集合，接入前建议先拉取一次。
  2. 接入时请直接采用本文档对应模型的接口与请求格式。
  3. Gemini 系列使用本文档中的原生接口与请求格式。
  4. 视频接口为异步任务接口，不能按普通文本接口理解。
  5. TTS 返回的是音频二进制内容，客户端要按文件流保存。