API 文档

OpenAI 兼容的 API 接口,一个 API Key 调用所有主流 AI 模型

基础信息 认证方式 聊天补全 图像生成 视频生成 语音合成 语音识别 文本嵌入 模型列表 支持的模型 错误处理 速率限制

🔗 Base URL

https://toapis.com/v1

所有 API 请求都应该使用此基础 URL。该接口完全兼容 OpenAI SDK,您只需修改 base_url 即可无缝迁移。

🔐 认证方式

所有 API 请求都需要在 HTTP 头部包含 API Key 进行认证:

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

您可以在 控制台 → API 令牌 页面创建和管理您的 API Key。

请妥善保管您的 API Key,不要在客户端代码中暴露。建议使用环境变量或服务端代理方式调用 API。
POST /v1/chat/completions

创建聊天补全。支持 GPT-4o、Claude 3.5、Gemini 2.0 等所有主流模型,完全兼容 OpenAI 格式。

请求参数

参数 类型 说明
model必填 string 模型名称,如 gpt-4o、claude-3-5-sonnet、gemini-2.0-flash
messages必填 array 消息数组,包含 role(system/user/assistant)和 content 字段
stream可选 boolean 是否开启流式响应,默认 false。推荐开启以获得更好的用户体验
temperature可选 number 采样温度,范围 0-2,默认 1。值越高输出越随机
max_tokens可选 integer 最大输出 token 数,不同模型有不同上限
top_p可选 number 核采样参数,范围 0-1,默认 1
frequency_penalty可选 number 频率惩罚,范围 -2 到 2,默认 0
presence_penalty可选 number 存在惩罚,范围 -2 到 2,默认 0
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://toapis.com/v1"
)

# 非流式调用
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一个有帮助的AI助手。"},
        {"role": "user", "content": "用Python写一个快速排序算法"}
    ],
    temperature=0.7,
    max_tokens=2000
)
print(response.choices[0].message.content)

# 流式调用
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[
        {"role": "user", "content": "介绍一下人工智能的发展历史"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://toapis.com/v1'
});

// 非流式调用
const response = await client.chat.completions.create({
    model: 'claude-3-5-sonnet',
    messages: [
        { role: 'system', content: '你是一个有帮助的AI助手。' },
        { role: 'user', content: '解释一下量子计算的基本原理' }
    ],
    temperature: 0.7
});
console.log(response.choices[0].message.content);

// 流式调用
const stream = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [
        { role: 'user', content: 'Hello!' }
    ],
    stream: true
});

for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
curl https://toapis.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的AI助手。"},
      {"role": "user", "content": "Hello!"}
    ],
    "stream": false,
    "temperature": 0.7
  }'

响应示例

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好!有什么我可以帮助你的吗?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 15,
    "total_tokens": 40
  }
}
POST /v1/images/generations

根据文本描述生成图像。支持 DALL-E 3、Gemini Imagen 等模型。

请求参数

参数 类型 说明
model可选 string 模型名称:dall-e-3、imagen-3.0-generate-002 等,默认 dall-e-3
prompt必填 string 图像描述文本,建议使用详细的英文描述以获得最佳效果
n可选 integer 生成图像数量,默认 1,DALL-E 3 最多支持 1 张
size可选 string 图像尺寸:1024x1024、1792x1024、1024x1792
quality可选 string 图像质量:standard(标准)或 hd(高清),仅 DALL-E 3 支持
style可选 string 图像风格:natural(自然)或 vivid(生动),仅 DALL-E 3 支持
response_format可选 string 返回格式:url(图片链接)或 b64_json(Base64编码)
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://toapis.com/v1"
)

response = client.images.generate(
    model="dall-e-3",
    prompt="A serene Japanese garden with cherry blossoms, koi pond, and a traditional wooden bridge, watercolor style",
    size="1024x1024",
    quality="hd",
    style="natural",
    n=1
)

print(response.data[0].url)
import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://toapis.com/v1'
});

const response = await client.images.generate({
    model: 'dall-e-3',
    prompt: 'A futuristic city at sunset, cyberpunk style, neon lights',
    size: '1792x1024',
    quality: 'hd',
    n: 1
});

console.log(response.data[0].url);
curl https://toapis.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A cute robot reading a book in a cozy library",
    "size": "1024x1024",
    "quality": "hd",
    "n": 1
  }'

响应示例

{
  "created": 1699000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A serene Japanese garden..."
    }
  ]
}
POST /v1/videos/generations

根据文本描述生成视频。支持 Google Veo 3.1 等模型。视频生成需要较长时间(通常 1-5 分钟)。

请求参数

参数 类型 说明
model可选 string 模型名称:veo-3.1-generate-preview,默认 veo-3.1-generate-preview
prompt必填 string 视频描述文本,建议使用详细的场景、动作、风格描述
aspect_ratio可选 string 画面比例:16:9(横屏)、9:16(竖屏)、1:1(方形),默认 16:9
resolution可选 string 分辨率:720p、1080p、4k,默认 720p。4k 需要更长生成时间
duration可选 string 视频时长:4(4秒)或 8(8秒),默认 4
视频生成是异步操作,通常需要 1-5 分钟完成。请确保您的请求超时设置足够长。4K 分辨率视频生成时间更长。
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "veo-3.1-generate-preview",
        "prompt": "A golden retriever running through a field of sunflowers at sunset, cinematic quality, slow motion",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
        "duration": "4"
    },
    timeout=600  # 10 分钟超时
)

result = response.json()
print(result["data"][0]["url"])
curl https://toapis.com/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "A timelapse of clouds moving over a mountain landscape",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": "8"
  }'

响应示例

{
  "created": 1699000000,
  "data": [
    {
      "url": "https://toapis.com/uploads/videos/video_xxx.mp4"
    }
  ],
  "status": "completed"
}
POST /v1/audio/speech

将文本转换为语音(TTS)。支持多种音色和语言。

请求参数

参数 类型 说明
model必填 string 模型名称:tts-1(标准)或 tts-1-hd(高清)
input必填 string 要转换的文本内容,最大 4096 字符
voice必填 string 音色:alloy、echo、fable、onyx、nova、shimmer
response_format可选 string 音频格式:mp3、opus、aac、flac,默认 mp3
speed可选 number 语速,范围 0.25-4.0,默认 1.0
from openai import OpenAI
from pathlib import Path

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://toapis.com/v1"
)

speech_file_path = Path("speech.mp3")
response = client.audio.speech.create(
    model="tts-1-hd",
    voice="nova",
    input="你好,欢迎使用我们的语音合成服务!",
    speed=1.0
)

response.stream_to_file(speech_file_path)
print(f"Audio saved to {speech_file_path}")
curl https://toapis.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello, this is a test of the text to speech API.",
    "voice": "alloy"
  }' \
  --output speech.mp3
不同音色特点:
alloy - 中性、平衡
echo - 男声、沉稳
fable - 英式口音
onyx - 深沉男声
nova - 女声、温和
shimmer - 女声、活泼
POST /v1/audio/transcriptions

将音频转录为文本(语音识别)。支持 Whisper 模型,可识别多种语言。

请求参数

参数 类型 说明
file必填 file 音频文件,支持 mp3、mp4、mpeg、mpga、m4a、wav、webm 格式,最大 25MB
model必填 string 模型名称:whisper-1
language可选 string 音频语言,ISO-639-1 格式,如 zh(中文)、en(英语)、ja(日语)
response_format可选 string 输出格式:json、text、srt、vtt,默认 json
prompt可选 string 提示文本,帮助模型理解上下文或专业术语
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://toapis.com/v1"
)

audio_file = open("meeting.mp3", "rb")
transcript = client.audio.transcriptions.create(
    model="whisper-1",
    file=audio_file,
    language="zh",
    response_format="text"
)

print(transcript)
curl https://toapis.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-your-api-key" \
  -F file="@meeting.mp3" \
  -F model="whisper-1" \
  -F language="zh" \
  -F response_format="text"

响应示例 (JSON 格式)

{
  "text": "这是转录后的文本内容,支持多种语言的自动识别。"
}
POST /v1/embeddings

创建文本嵌入向量。可用于语义搜索、文本分类、聚类、推荐系统等任务。

请求参数

参数 类型 说明
model必填 string 模型名称:text-embedding-3-small、text-embedding-3-large、text-embedding-ada-002
input必填 string | array 输入文本或文本数组,单个文本最大 8191 tokens
dimensions可选 integer 向量维度,仅 text-embedding-3-* 支持
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://toapis.com/v1"
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["人工智能正在改变世界", "机器学习是AI的一个分支"],
    dimensions=512  # 可选,减小向量维度
)

for i, embedding in enumerate(response.data):
    print(f"文本 {i+1} 的嵌入向量维度: {len(embedding.embedding)}")
curl https://toapis.com/v1/embeddings \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "人工智能正在改变世界"
  }'

响应示例

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0023, -0.0093, 0.0156, ...],
      "index": 0
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}
GET /v1/models

列出当前可用的所有模型。

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://toapis.com/v1"
)

models = client.models.list()

for model in models.data:
    print(f"{model.id} - {model.owned_by}")
curl https://toapis.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

支持的模型

💬 聊天模型

GPT-4o

OpenAI 最新多模态模型,支持文本、图像、音频

gpt-4o

GPT-4o Mini

GPT-4o 的轻量版,性价比高

gpt-4o-mini

Claude 3.5 Sonnet

Anthropic 最强模型,编程能力出众

claude-3-5-sonnet

Claude 3.5 Haiku

Claude 系列最快模型

claude-3-5-haiku

Gemini 2.0 Flash

Google 最新模型,速度快、支持多模态

gemini-2.0-flash

Gemini 2.5 Pro

Google 最强推理模型

gemini-2.5-pro-preview

DeepSeek V3

国产开源大模型,性能优秀

deepseek-chat

DeepSeek R1

推理增强模型,擅长复杂推理

deepseek-reasoner

🎨 图像生成

DALL-E 3

OpenAI 图像生成,高质量、理解力强

dall-e-3

Imagen 3

Google 图像生成,细节丰富

imagen-3.0-generate-002

🎬 视频生成

Veo 3.1

Google 视频生成,支持 4K、8 秒视频

veo-3.1-generate-preview

🎵 音频模型

TTS-1

文本转语音,标准质量

tts-1

TTS-1 HD

文本转语音,高清质量

tts-1-hd

Whisper

语音转文本,支持多语言

whisper-1

📊 嵌入模型

Text Embedding 3 Small

轻量嵌入模型,512-1536 维

text-embedding-3-small

Text Embedding 3 Large

高精度嵌入模型,最高 3072 维

text-embedding-3-large

错误处理

API 使用标准 HTTP 状态码表示请求结果。错误响应包含详细的错误信息。

状态码 错误类型 说明
400 invalid_request_error 请求参数错误,如缺少必填字段、参数格式错误
401 authentication_error API Key 无效或未提供
403 permission_error 无权访问该资源或功能
404 not_found_error 请求的资源不存在
429 rate_limit_error 请求频率超限,请稍后重试
500 server_error 服务器内部错误
503 service_unavailable 服务暂时不可用,如上游服务故障

错误响应示例

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
建议在代码中实现重试机制,对于 429 和 5xx 错误进行指数退避重试。

速率限制

为保证服务稳定性,API 对请求频率有一定限制。限制基于您的账户等级和余额。

限制类型 免费用户 付费用户
每分钟请求数 (RPM) 20 500
每天请求数 (RPD) 200 无限制
每分钟 Token 数 (TPM) 40,000 2,000,000
单次最大 Token 4,096 128,000

当达到速率限制时,API 将返回 429 状态码。响应头中包含以下信息: