OpenAI 兼容接口

QuotaAPI 提供 OpenAI 兼容接口，适合 OpenAI SDK、Codex CLI、IDE 插件、Agent 框架和自建服务端调用。

Base URL

https://quotarouter.ai/v1

认证方式：

Authorization: Bearer YOUR_QUOTAAPI_KEY

Chat Completions

curl https://quotarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "Explain QuotaAPI in one sentence." }
    ],
    "temperature": 0.7,
    "max_tokens": 120
  }'

Responses

curl https://quotarouter.ai/v1/responses \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Give me a short API connectivity test.",
    "max_output_tokens": 120
  }'

Embeddings

curl https://quotarouter.ai/v1/embeddings \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-large",
    "input": "QuotaAPI provides one API entry point for AI applications."
  }'

Embeddings 适合检索增强、语义搜索、相似度匹配和知识库索引。该接口需要使用 OpenAI / GPT 类型分组，并且请求体必须包含 model。

图片生成

curl https://quotarouter.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean technical dashboard illustration for QuotaAPI.",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

图片生成接口用于根据文本提示生成图片。它需要满足三个条件：

1. API Key 绑定 OpenAI / GPT 类型分组。
2. 分组已在控制台开启图片生成权限。
3. 模型使用 gpt-image-* 图片模型，例如 gpt-image-2。

如果省略 model，QuotaAPI 会使用默认图片模型 gpt-image-2。如果你在 SDK 里希望直接拿到图片内容，建议使用 response_format: "b64_json"；如果客户端支持 URL 响应，也可以按模型能力选择对应格式。

图片编辑

图片编辑支持 multipart 上传本地图片：

curl https://quotarouter.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Make the background darker and keep the object centered." \
  -F "[email protected]" \
  -F "size=1024x1024" \
  -F "response_format=b64_json"

也可以在 JSON 请求中传入图片 URL：

curl https://quotarouter.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Replace the background with a quiet product studio.",
    "images": [
      { "image_url": "https://example.com/input.png" }
    ],
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

图片编辑和图片生成使用同一套分组权限。若返回 Images API is not supported for this platform，通常表示当前 API Key 不是 OpenAI / GPT 类型分组；若返回 Image generation is not enabled for this group，需要在控制台开启该分组的图片生成权限。

Models

curl https://quotarouter.ai/v1/models \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY"

模型列表会受账号权限、分组和后台配置影响。生产环境建议在控制台确认模型名称后再写入客户端配置。

参数建议

参数	建议
model	使用控制台开放的模型名称
max_tokens	Chat Completions 使用该字段限制输出
max_completion_tokens	部分新模型支持该字段
max_output_tokens	Responses 使用该字段限制输出
stream	客户端支持流式时可设为 true
input	Responses 和 Embeddings 的主要输入字段
prompt	图片生成和图片编辑的文本提示
size	图片尺寸，例如 1024x1024；计费记录会按图片数量和尺寸归档
response_format	图片接口可按模型能力选择 b64_json 或 URL 响应

对于带 reasoning 的模型，输出 token 设置过低可能导致请求被拒绝。建议最小值从 16 起步，正式任务按响应长度设置更高值。

错误处理

QuotaAPI 会尽量保留上游错误的状态码和消息。客户端应至少处理：

状态码	含义
400	请求体、模型名称或参数不合法
401	API Key 无效
402	余额不足
403	无权限访问目标分组、模型，或分组未开启图片生成
429	触发限流或并发限制
500	服务端异常，需要结合请求记录排查

TIP

服务端集成建议把 https://quotarouter.ai/v1 和 YOUR_QUOTAAPI_KEY 放入环境变量，不要硬编码在代码里。