{"openapi": "3.1.0", "info": {"title": "openbat.ai API", "version": "1.0.0", "summary": "OpenAI-compatible gateway to 100+ AI models through one API key.", "description": "OpenAI-compatible AI gateway — call OpenAI / Anthropic Claude / Google Gemini / AWS Bedrock / Alibaba Qwen / ByteDance Doubao and more through a single API key and a single base URL.\n\n**Auth**: send `Authorization: Bearer sk-...` on every request. Get a key at https://openbat.ai/register.\n\n**Drop-in**: point any OpenAI SDK at the server URL below — no other change.\n\n**Agents**: an MCP server is available at https://mcp.router.ai/mcp (official MCP Registry: `ai.router/ai-gateway`) exposing the same capabilities as tools plus live catalog/pricing/reference resources.\n\nUnified AI gateway — one API key for OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, Alibaba Qwen, ByteDance Doubao and 100+ other models. OpenAI-compatible protocol, real-time usage billing, covering chat, image, video, embedding and speech.", "contact": {"name": "openbat.ai", "url": "https://openbat.ai"}}, "servers": [{"url": "https://api.router.ai", "description": "Production"}], "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "description": "API key issued by the gateway. Format: `Bearer sk-...`."}}}, "security": [{"bearerAuth": []}], "tags": [{"name": "AI Gateway", "description": "OpenAI-compatible endpoints for chat, image, video, embedding and audio models."}], "externalDocs": {"description": "openbat.ai API reference", "url": "https://openbat.ai/docs/api"}, "x-mcp": {"endpoint": "https://mcp.router.ai/mcp", "transport": "streamable-http", "registry": "ai.router/ai-gateway", "auth": {"type": "http-header", "header": "Authorization", "format": "Bearer <api-key>"}}, "x-llms-txt": "https://openbat.ai/llms.txt", "x-signup-url": "https://openbat.ai/register", "paths": {"/v1/chat/completions": {"post": {"summary": "创建对话请求 (OpenAI 兼容)", "description": "兼容 OpenAI Chat Completions 协议, 一套接口调用 Claude / Gemini 等主流大模型", "operationId": "create-chat-completion", "tags": ["AI Gateway"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"model": {"type": "string", "description": "模型 ID, 如 `claude-opus-4-7` / `claude-sonnet-4-6` / `gemini-2.5-pro` / `gemini-2.5-flash`", "example": "claude-sonnet-4-6"}, "messages": {"type": "array", "description": "对话消息数组, 按时间顺序传入 system / user / assistant", "items": {"type": "object", "properties": {"role": {"type": "string", "enum": ["system", "user", "assistant", "tool"]}, "content": {"type": "string", "description": "消息内容 (字符串, 或多模态数组 `[{\"type\":\"text\",\"text\":\"...\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"...\"}}]`)"}, "name": {"type": "string", "description": "(可选) 消息作者标识"}, "tool_call_id": {"type": "string", "description": "(仅 role=tool) 对应的 tool_call id"}}, "required": ["role", "content"]}}, "temperature": {"type": "number", "description": "采样温度, 值越高输出越随机, 建议 0.7 左右。与 `top_p` 二选一", "default": 1, "minimum": 0, "maximum": 2}, "top_p": {"type": "number", "description": "核采样", "default": 1, "minimum": 0, "maximum": 1}, "max_tokens": {"type": "integer", "description": "生成 token 上限"}, "stream": {"type": "boolean", "description": "是否以 SSE 流式返回", "default": false}, "stop": {"type": "array", "description": "停止序列, 最多 4 个", "items": {"type": "string"}}, "presence_penalty": {"type": "number", "default": 0, "minimum": -2, "maximum": 2}, "frequency_penalty": {"type": "number", "default": 0, "minimum": -2, "maximum": 2}, "tools": {"type": "array", "description": "工具定义数组 (function calling)", "items": {"type": "string"}}, "response_format": {"type": "object", "description": "(可选) 响应格式约束, 如 `{\"type\":\"json_object\"}` 强制 JSON 输出"}, "user": {"type": "string", "description": "(可选) 终端用户标识"}}, "required": ["model", "messages"]}}}}, "responses": {"200": {"description": "返回 assistant 消息", "content": {"application/json": {"example": {"id": "chatcmpl-abc123", "object": "chat.completion", "created": 1713225600, "model": "claude-sonnet-4-6", "choices": [{"index": 0, "message": {"role": "assistant", "content": "你好! 我是 AI 助手。"}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 8, "completion_tokens": 16, "total_tokens": 24}}}}}}}}, "/v1/videos/generations/{id}": {"get": {"summary": "查询视频任务", "description": "按任务 ID 查看生成进度与结果 URL", "operationId": "get-video-task", "tags": ["AI Gateway"], "parameters": [{"name": "id", "in": "path", "required": true, "description": "任务 ID (BytePlus 返的 cgt-* 或本平台 ID)", "schema": {"type": "string", "description": "任务 ID (BytePlus 返的 cgt-* 或本平台 ID)", "example": "cgt-20260428143025-abc123"}}], "responses": {"200": {"description": "任务详情 (BytePlus 原生格式 + 平台扩展). 终态时含 content / usage / seed"}}}}, "/v1/images/generations": {"post": {"summary": "Aliyun Qwen-Image (多模态图像生成 / 编辑)", "description": "", "operationId": "aliyun-qwen-image-multimodal", "tags": ["AI Gateway"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"model": {"type": "string", "description": "Qwen-Image multimodal 模型. `-2.0` / `-2.0-pro` / `-max` 文生图; `-edit*` 系列需 1-3 张参考图编辑", "enum": ["qwen-image-2.0", "qwen-image-2.0-pro", "qwen-image-max", "qwen-image-edit", "qwen-image-edit-plus", "qwen-image-edit-max"], "example": "qwen-image-edit"}, "input": {"type": "object", "description": "输入对象, 包含 messages 数组", "properties": {"messages": {"type": "array", "description": "对话消息数组. 当前 image 场景仅支持单个 user message", "items": {"type": "object", "properties": {"role": {"type": "string", "description": "消息角色, 当前仅 user", "enum": ["user"], "example": "user"}, "content": {"type": "array", "description": "内容块数组. 必须含至少 1 个 `{text}`. 编辑类模型必须再含 1-3 个 `{image}` 参考图", "items": {"type": "object", "properties": {"text": {"type": "string", "description": "文本提示词 (单 content block 内仅 `text` 或 `image` 二选一)", "example": "把这张图改成赛博朋克风格, 加上霓虹灯"}, "image": {"type": "string", "description": "参考图 URL (https), Aliyun 上游内部下载. URL 必须公网可达", "example": "https://example.com/reference.png", "format": "url"}}}}}, "required": ["role", "content"]}}}, "required": ["messages"]}, "parameters": {"type": "object", "description": "生成参数", "properties": {"size": {"type": "string", "description": "图像尺寸, DashScope 风格 (`*` 分隔)", "enum": ["1024*1024", "1664*928", "1472*1140", "1328*1328", "1140*1472", "928*1664", "1280*720", "720*1280"], "default": "1024*1024", "example": "1024*1024"}, "n": {"type": "integer", "description": "生成张数, 当前上游限单次 1 张", "default": 1, "example": 1, "minimum": 1, "maximum": 1}, "seed": {"type": "integer", "description": "随机种子. 同 prompt + 同 seed 可复现近似结果, 便于风格调优", "example": 42}, "watermark": {"type": "boolean", "description": "是否添加水印", "default": false, "example": false}, "negative_prompt": {"type": "string", "description": "负向提示词 — 模型应避免的元素", "example": "blurry, low quality"}, "prompt_extend": {"type": "boolean", "description": "是否启用 prompt 智能扩展 (上游自动补充细节)", "default": true, "example": true}}}}, "required": ["model", "input"]}}}}, "responses": {"200": {"description": "生成成功, 返回图片 URL", "content": {"application/json": {"example": {"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "output": {"choices": [{"finish_reason": "stop", "message": {"role": "assistant", "content": [{"image": "https://dashscope-result-sgp.oss-ap-southeast-1.aliyuncs.com/xyz/edited.png?Expires=1715587200&OSSAccessKeyId=xxx&Signature=xxx"}]}}]}, "usage": {"image_count": 1, "height": 1024, "width": 1024}}}}}, "400": {"description": "参数错误, 编辑类模型未传参考图 / model 名不识别 / size 不支持等", "content": {"application/json": {"example": {"code": "InvalidParameter", "message": "For image editing, the message must contain 1~3 image content items. Got 0 image items.", "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}}, "429": {"description": "请求频次或并发超限", "content": {"application/json": {"example": {"code": "Throttling.RateQuota", "message": "Request rate quota exceeded, please retry after a short delay.", "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}}}}}, "/v1/images/edits": {"post": {"summary": "OpenAI GPT Image 图生图 (i2i)", "description": "", "operationId": "openai-gpt-image-edit", "tags": ["AI Gateway"], "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"type": "object", "properties": {"image": {"type": "string", "description": "原始图像文件 (PNG / JPEG / WebP). 单张时字段名为 `image`; 多张参考图请重复使用字段名 `image[]` (部分模型支持多图输入)", "example": "@photo.png"}, "model": {"type": "string", "description": "图像模型 ID (如 `gpt-image-2` (推荐) / `gpt-image-1` / `dall-e-2`)", "example": "gpt-image-2"}, "prompt": {"type": "string", "description": "编辑指令文本; 描述越具体生成质量越高 (支持中英文)", "example": "把背景换成赛博朋克霓虹街道, 保留人物主体不变"}, "mask": {"type": "string", "description": "蒙版图像 (PNG; 透明区域为编辑目标). 仅部分模型支持局部编辑模式", "example": "@mask.png"}, "n": {"type": "integer", "description": "生成图片数量", "default": 1, "minimum": 1, "maximum": 10}, "size": {"type": "string", "description": "图像尺寸 (宽×高). i2i 端点 (`/v1/images/edits`) **不支持 2K / 4K**, 仅官方明文挡位: `gpt-image-1 / gpt-image-2` → `1024x1024` / `1024x1536` / `1536x1024`; `dall-e-2` → `256x256` / `512x512` / `1024x1024`. 需要 2K / 4K 高分辨率请走 t2i 端点 `/v1/images/generations` (gpt-image-2 支持 freeform 自定义, 16 倍数 / ≤3840px / 长短比 ≤3:1)", "enum": ["auto", "1024x1024", "1024x1536", "1536x1024", "256x256", "512x512"], "default": "auto"}, "quality": {"type": "string", "description": "质量档位. `low/medium/high` 是原生三档; `standard/hd` 是 DALL-E 兼容 alias", "enum": ["auto", "low", "medium", "high", "standard", "hd"], "default": "auto"}, "response_format": {"type": "string", "description": "返回格式. `gpt-image-*` 始终返 `b64_json`; `url` 仅 DALL-E 系列生效", "enum": ["b64_json", "url"], "default": "b64_json"}, "output_format": {"type": "string", "description": "输出图像编码格式 (仅 `gpt-image-*` 支持)", "enum": ["png", "jpeg", "webp"], "default": "png"}, "background": {"type": "string", "description": "背景类型; `transparent` 需配合 `output_format=png` 或 `webp`", "enum": ["transparent", "opaque", "auto"], "default": "auto"}, "user": {"type": "string", "description": "客户端可选传入的最终用户标识 (用于上游滥用检测)"}}, "required": ["image", "model", "prompt"]}}}}, "responses": {"200": {"description": "成功返回编辑后的图像 (含 base64). usage.input_tokens_details.image_tokens 反映输入图像消耗的视觉 token (跟文生图差异点)", "content": {"application/json": {"example": {"created": 1713225600, "data": [{"b64_json": "iVBORw0KGgoAAAANSUhEUgAA... (base64, 截断显示)"}], "background": "opaque", "output_format": "png", "quality": "high", "size": "1024x1024", "usage": {"input_tokens": 522, "input_tokens_details": {"text_tokens": 18, "image_tokens": 504}, "output_tokens": 7024, "total_tokens": 7546}}}}}, "400": {"description": "请求参数错误 (mask 尺寸跟 image 不匹配 / 不支持的图像格式 / model 不支持 mask 等)", "content": {"application/json": {"example": {"error": {"message": "Mask dimensions must match image dimensions.", "type": "invalid_request_error", "code": "invalid_mask"}}}}}, "402": {"description": "余额不足", "content": {"application/json": {"example": {"error": {"message": "Insufficient balance"}}}}}}}}, "/v1/videos/generations": {"post": {"summary": "Aliyun Wan 视频生成", "description": "Aliyun Wan 2.5+ 异步 t2v/i2v/r2v 视频生成", "operationId": "aliyun-wan-video", "tags": ["AI Gateway"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"model": {"type": "string", "description": "视频生成模型. 后缀 t2v/i2v/r2v 决定 input 字段; 主版本号 2.6/2.7 决定协议格式 (见介绍)", "enum": ["wan2.6-t2v", "wan2.7-t2v", "wan2.7-t2v-2026-04-25", "wan2.5-t2v-preview", "wan2.6-i2v", "wan2.6-i2v-flash", "wan2.7-i2v", "wan2.7-i2v-2026-04-25", "wan2.5-i2v-preview", "wan2.6-r2v", "wan2.6-r2v-flash", "wan2.7-r2v"], "example": "wan2.7-t2v"}, "duration": {"type": "integer", "description": "视频时长 (秒). 网关计费用, 必填", "default": 5, "example": 5}, "resolution": {"type": "string", "description": "分辨率档位 (网关计费用). 480p 仅 wan2.5-*-preview 支持; Wan 2.7 大部分仅 720p; 客户端额外在 parameters 里也要传 (Wan 2.7 用 resolution=\"720P\" 大写, Wan 2.6 用 size=\"1280*720\")", "enum": ["480p", "720p", "1080p"], "default": "720p", "example": "720p"}, "aspect_ratio": {"type": "string", "description": "宽高比 (网关计费用)", "default": "16:9", "example": "16:9"}, "input": {"type": "object", "description": "上游 input 字段, 完全透传. 字段名按 model 版本不同:\n- Wan 2.7+: `prompt` + `media: [{type, url}]` (type 取值: reference_video / reference_image / first_frame / driving_audio)\n- Wan 2.6 r2v: `prompt` + `reference_urls: [\"url1\",\"url2\"]` (字符串数组)\n- Wan 2.6 i2v: `prompt` + `img_url` (单 URL) + `audio_url` (单 URL, 可选)\n- Wan 2.6/2.7 t2v: 仅 `prompt`"}, "parameters": {"type": "object", "description": "上游 parameters 字段, 完全透传:\n- Wan 2.7+: `resolution: \"720P\"` (大写P) + `duration` + `prompt_extend` (bool) + `watermark` (bool)\n- Wan 2.6: `size: \"1280*720\"` + `duration` + `audio` (bool) + `shot_type: \"multi\"` + `prompt_extend`"}, "webhook_url": {"type": "string", "description": "终态推送回调 URL (可选). 不传则主动 GET /v1/videos/generations/{id} 轮询"}}, "required": ["model", "duration", "resolution", "input"]}}}}, "responses": {"202": {"description": "任务已提交, 异步生成中"}, "200": {"description": "GET /v1/videos/generations/{id} 查询终态"}}}}, "/v1/messages": {"post": {"summary": "Claude Code 接入配置教程", "description": "Claude Code (官方 CLI) 通过两个环境变量指向我方网关, 直接使用全部 Claude / Bedrock 模型", "operationId": "claude-code-setup", "tags": ["AI Gateway"], "responses": {"200": {"description": "成功", "content": {"application/json": {"example": ""}}}}}}, "/v1/embeddings": {"post": {"summary": "文本向量化 (Embeddings)", "description": "将文本转成向量表示, 用于语义检索 / 聚类 / 相似度", "operationId": "create-embedding", "tags": ["AI Gateway"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"model": {"type": "string", "description": "向量模型 ID。可选: `text-embedding-v4` (多语言, 默认 1024 维, 支持自定义维度) / `text-embedding-004` / `gemini-embedding-001` / `gemini-embedding-2-preview` / `voyage-4-large` / `voyage-4` / `voyage-4-lite` (Voyage, 默认 1024 维, 支持 256/512/1024/2048)", "example": "text-embedding-v4"}, "input": {"type": "string", "description": "待向量化的文本, 或字符串数组 (批量)。数组长度按需分片, 返回向量按 `index` 顺序对应。"}, "encoding_format": {"type": "string", "description": "向量编码格式, 省略走默认 `float`。", "enum": ["float", "base64"], "default": "float"}, "dimensions": {"type": "integer", "description": "(可选) 自定义输出向量维度。`text-embedding-v4` 默认 1024 维, 可传该参数截断到更小维度 (省略走模型默认)。"}}, "required": ["model", "input"]}}}}, "responses": {"200": {"description": "返回向量数组", "content": {"application/json": {"example": {"object": "list", "model": "text-embedding-v4", "data": [{"object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789]}], "usage": {"prompt_tokens": 8, "total_tokens": 8}}}}}}}}, "/v1/audio/speech": {"post": {"summary": "文本转语音 (千问 TTS)", "description": "qwen3-tts-flash / qwen3-tts-instruct-flash 多语言多音色文本转语音, 同步返回 audio bytes", "operationId": "aliyun-tts", "tags": ["AI Gateway"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"model": {"type": "string", "description": "TTS 模型. `qwen3-tts-flash` 基础版; `qwen3-tts-instruct-flash` 支持 `instructions` 控制情感/语速", "enum": ["qwen3-tts-flash", "qwen3-tts-instruct-flash"], "example": "qwen3-tts-flash"}, "input": {"type": "string", "description": "待合成的文本. 中英混合 OK. 按字符数计费", "example": "你好世界, 今天天气不错"}, "voice": {"type": "string", "description": "音色名. Aliyun 系: `Cherry` (默认) / `Ethan` / 其他. 不传或传 OpenAI 风格 (alloy/echo/...) 会 fallback 到 `Cherry`", "default": "Cherry", "example": "Cherry"}, "response_format": {"type": "string", "description": "音频格式. `qwen3-tts-flash` 接受 `mp3`/`wav`; `qwen3-tts-instruct-flash` 上游不接受此字段, 默认输出 `wav`", "enum": ["mp3", "wav"], "default": "mp3"}, "instructions": {"type": "string", "description": "(仅 `qwen3-tts-instruct-flash`) 自然语言指令, 控制语气/语速/情感", "example": "Speak with excitement and a fast pace."}, "speed": {"type": "number", "description": "(OpenAI 兼容字段) Aliyun 系不生效, 改用 `instructions` 描述"}}, "required": ["model", "input"]}}}}, "responses": {"200": {"description": "成功返回音频二进制流"}, "400": {"description": "参数错误 (model 不支持 / voice 不存在 / input 为空 等), 透传上游 error 原文", "content": {"application/json": {"example": {"error": {"message": "Invalid voice specified", "type": "invalid_request_error", "code": "endpoint_model_mismatch"}}}}}}}}}}