# KovAPI API 开发者文档

OpenAI-compatible AI API 网关。Base URL: `https://kovapi.com/v1`

## 认证
所有请求需带 Bearer Token：
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 模型与价格
| 模型 | 能力 | 端点 | 价格 |
| --- | --- | --- | --- |
| gpt-5.6-sol | 前沿推理、Agentic 编程、长链路任务、结构化输出 | /chat/completions | 输入 $1.2/1M · 输出 $6.0/1M |
| gpt-5.6-luna | 高速对话、Agentic 编程、大批量低延迟、结构化输出 | /chat/completions | 输入 $0.07/1M · 输出 $0.4/1M |
| gpt-6-astra | 深度推理、Agentic 编程、超长上下文、图片输入、结构化输出 | /chat/completions | 输入 $3.0/1M · 输出 $15.0/1M |
| gpt-6.2-astra | 复杂推理、Agentic 编程、长文档分析、超长上下文、图片输入、工具调用、结构化输出 | /chat/completions | 输入 $2.4/1M · 输出 $12.0/1M |
| gpt-6.2-sol | Agentic 编程、复杂编码、专业文档与分析、推理、超长上下文、图片输入、工具调用、结构化输出 | /chat/completions | 输入 $0.6/1M · 输出 $3.0/1M |
| gpt-6.1-sol | Agentic 编程、复杂编码、专业文档与分析工作、推理、超长上下文、图片输入、结构化输出 | /chat/completions | 输入 $0.6/1M · 输出 $3.0/1M |
| gpt-6-sol | 复杂编码、Agentic 工作流、推理、超长上下文、图片输入、结构化输出 | /chat/completions | 输入 $0.6/1M · 输出 $3.0/1M |
| gpt-6-luna | 大批量对话、低延迟 Agent 步骤、分类与抽取、超长上下文、结构化输出 | /chat/completions | 输入 $0.07/1M · 输出 $0.4/1M |
| gpt-image-2 | 文生图、图生图、封面、海报、插画 | /images/generations | 1K $0.005 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-flare | 文生图、图生图、封面、海报、插画、文字排版 | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 |
| gpt-image-2.5-sunburst | 文生图、图生图、封面、海报、插画、文字排版 | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 |
| gpt-image-2.6-flare | 文生图、图生图、封面、海报、插画、文字排版 | /images/generations | 1K $0.015 · 2K $0.03 · 4K $0.05 |
| gpt-image-2.6-sunburst | 文生图、图生图、封面、海报、插画、文字排版 | /images/generations | 1K $0.015 · 2K $0.03 · 4K $0.05 |
| gpt-image-2.6-flare-token | 文生图、图生图、封面、海报、插画、文字排版 | /images/generations | 1K $0.0 · 2K $0.0 · 4K $0.0 |
| gpt-image-2.6-sunburst-token | 文生图、图生图、封面、海报、插画、文字排版 | /images/generations | 1K $0.0 · 2K $0.0 · 4K $0.0 |
| nano-banana-2 | 文生图、图生图、封面、海报、插画 | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-pro | 文生图、图生图、封面、海报、插画、信息图 | /images/generations | 1K $0.02 · 2K $0.03 · 4K $0.05 |
| nano-banana-2.1 | 文生图、改图、多图合成、海报与信息图、商品图、宽幅横幅 | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-2-lite | 文生图、多图合成、社交配图、商品图、广告多版本、批量草图、宽幅横幅 | /images/generations | 1K $0.01 |
| grok-imagine-image | 文生图、改图、海报、产品图、社交配图、中英文文字 | /images/generations | 1K $0.005 · 2K $0.005 |
| grok-imagine-image-quality | 封面、海报、商品图、插画、文生图与改图 | /images/generations | 1K $0.015 · 2K $0.02 |
| seedream-5.0-pro | 文生图、改图、多图融合（最多 8 张参考图）、海报与图中文字、商品图、21:9 宽幅 | /images/generations | 1K $0.025 · 2K $0.045 |
| seedream-5.5 | 文生图、改图、多图融合（最多 10 张参考图）、连续多轮修改、海报与图中文字、21:9 / 9:21 长图 | /images/generations | 1K $0.02 · 2K $0.03 |
| kling-image-4.0 | 文生图、参考图生图（最多 10 张参考图）、图中文字与海报排版、写实摄影、2K / 4K、8 种比例（含 21:9） | /images/generations | 2K $0.06 · 4K $0.09 |
| kling-image-4.0-long | 电商详情页长图（1–3 张商品图，短 / 中 / 长三种篇幅）、网页设计长图（纯文字或加主体 / 风格参考图）、1K / 2K | /images/generations | 1K $0.235 · 2K $0.28 |
| midjourney | 文生图（V8.2 / 8.1 / 8 / 7 / 6.1 / 6、Niji 7 / 6）、垫图（最多 5 张）、放大、变体、Remix、重跑、扩图、平移、局部重绘、Blend、Edit，参数照官方写法 | /images/generations | 1K $0.045 |
| claude-sonnet-4-6 | 对话、代码、推理、长上下文 | /chat/completions | 输入 $1.5/1M · 输出 $7.5/1M |
| claude-opus-5 | 深度推理、代码、Agent、长上下文、图片理解 | /chat/completions | 输入 $4.0/1M · 输出 $20.0/1M |
| claude-fable-5 | 中文写作、叙事创作、长文生成、对话、代码、图片理解 | /chat/completions | 输入 $8.0/1M · 输出 $40.0/1M |
| claude-opus-5-5 | 复杂推理、长程 Agent 编码、代码工程、工具调用、图片与 PDF 理解 | /chat/completions | 输入 $2.5/1M · 输出 $12.5/1M |
| claude-sonnet-5-5 | 日常编码与 Agent、长上下文、工具调用、图片与 PDF 理解、规模化生产流量 | /chat/completions | 输入 $1.5/1M · 输出 $7.5/1M |
| gemini-4-argon | Beta · 推理 · 长上下文 | /chat/completions | 输入 $0.5/1M · 输出 $3.0/1M |
| gemini-4-neon | Beta · 推理 · 编程 · 长上下文 | /chat/completions | 输入 $0.9/1M · 输出 $4.5/1M |
| gemini-4-hydrogen | Beta · 推理 · 长上下文 | /chat/completions | 输入 $0.45/1M · 输出 $2.25/1M |
| gemini-3.8-flash | 对话、推理、自适应思考、图片输入、超长上下文 | /chat/completions | 输入 $0.6/1M · 输出 $3.6/1M |
| deepseek-v4.1-flash | 对话、推理、代码、工具调用、思考模式可开关 | /chat/completions | 输入 $0.075/1M · 输出 $0.3/1M |
| glm-5.3 | 对话、代码、Agent 工作流、推理、中英文写作、工具调用 | /chat/completions | 输入 $1.12/1M · 输出 $3.52/1M |
| qwen3.8-max | 推理、代码、Agent 与工具调用、中英文写作、图片理解 | /chat/completions | 输入 $1.4/1M · 输出 $4.2/1M |
| grok-4.7 | 复杂推理、代码、长文档分析、工具调用、结构化输出、图片理解 | /chat/completions | 输入 $0.3/1M · 输出 $0.9/1M |
| veo-3.1 | 短片、产品动效、首尾帧过渡、商业成片 | /videos/generations | $0.2 / 条 |
| gemini-omni-1.2-flash | 多镜头短片、首尾帧过渡、角色参考、改已有视频 | /videos/generations | $0.035 / 秒（3–15 秒，按秒计费） |
| gemini-omni-flash | 多镜头短片、分镜叙事、首尾帧过渡 | /videos/generations | $0.035 / 秒（6–10 秒，按秒计费） |
| seedance-2.5-token | 文字、图片、视频与音频参考 | /videos/generations | USD / 1M video tokens: 480p/720p $10.2 ($6.1 with reference video); 1080p $11.1 ($6.7 with reference video). |
| seedance-2.5-token-draft | 文字、图片、视频与音频参考 | /videos/generations | USD / 1M video tokens: 480p draft $10.2 ($6.1 with reference video). Upgrade billed separately. |
| seedance-2.5 | 长镜头短片、多参考素材、商业成片 | /videos/generations | $0.158 / 秒（4–30 秒，按秒计费） |
| seedance-2.5-flash | 批量短片、商品视频、按参考素材出片 | /videos/generations | $0.12 / 秒（4–30 秒，按秒计费） |
| seedance-2.0 | 短片、商业素材 | /videos/generations | $0.105 / 秒（5–15 秒，按秒计费） |
| seedance-2.0-fast | 批量素材、快速验证创意 | /videos/generations | $0.075 / 秒（5–15 秒，按秒计费） |
| seedance-2.0-mini | 海量草稿、低成本试错 | /videos/generations | $0.052 / 秒（5–15 秒，按秒计费） |
| seedance-2.0-clip | 真人出镜短片、带货视频、批量成片 | /videos/generations | $1.0 / 条 |
| seedance-2.5-30s | 长镜头叙事、带货长片 | /videos/generations | $2.0 / 条 |
| wan3.0-video | 长镜头叙事、多素材合成、视频改写 | /videos/generations | $0.065 / 秒（4–30 秒，按秒计费） |
| wan3.0-video-prime | 赶工期的成片、批量试拍 | /videos/generations | $0.12 / 秒（4–30 秒，按秒计费） |
| minimax-h3 | 高清带声短片、首帧 / 首尾帧动画、多图参考（可加参考音频与参考视频） | /videos/generations | $0.036 / 秒（4–15 秒，按秒计费） |
| minimax-h3-lite | 批量出片、快速试提示词、参考图生视频 | /videos/generations | $0.0125 / 秒（4–15 秒，按秒计费） |
| grok-imagine-video-1.5 | 批量短视频、创意快速验证 | /videos/generations | $0.04 / 秒（4–15 秒，按秒计费） |

## 文本对话 (Chat Completions)
`POST /v1/chat/completions`，支持 `stream: true` 流式输出。
```bash
curl https://kovapi.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Hello"}]}'
```
图片识别（Vision）：在 `messages` 的 `content` 里传入 `image_url`（公网图片链接或 base64 data URL）即可识别图片：
```bash
curl https://kovapi.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":[{"type":"text","text":"这张图是什么?"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}]}'
```

## 图片生成 (Images) — 异步任务（提交即返回任务号）
图片接口统一为**异步任务**：提交后立刻返回 `HTTP 202` 与任务号 `id`（`{"id":"img_...","object":"image.generation.job","status":"queued"}`），再用任务号轮询 `GET /v1/images/jobs/{id}` 直到 `status` 变为 `succeeded`，结果在 `data[0].url`（`img.kovapi.com` 直链，保留 7 天，请及时下载或转存）。**不要**期望提交即返回 `data`。
**文生图** `POST /v1/images/generations`（**图生图**：用 `POST /v1/images/edits`，或在 generations 里加 `image`，两者等价；`image` 可传公网 URL、`data:` URI 或 base64）。
```bash
# 1) 提交任务 -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"gpt-image-2","prompt":"a poster","size":"2:3"}'
# 2) 轮询任务（每 2~3 秒一次，直到 status=succeeded，结果在 data[0].url）
curl https://kovapi.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
`size` 推荐直接传宽高比 `1:1` / `3:4` / `2:3` / `9:16` / `4:3` / `3:2` / `16:9`，模型按该比例**原生出图**（主体不会被裁切）；也兼容像素尺寸（如 `1024x1024` / `1024x1536` / `1536x1024`）。文生图、图生图均支持。`async` 字段已不再需要（传了会被忽略）。


## 视频生成 (Videos) — 异步任务（提交即返回任务号）
视频接口同为**异步任务**：`POST /v1/videos/generations` 提交后立刻返回 `HTTP 202` 与任务号（`{"id":"img_...","object":"video.generation.job","status":"queued"}`），再轮询 `GET /v1/videos/jobs/{id}` 直到 `status` 变为 `succeeded`，结果在 `data[0].url`（重托管的 mp4 直链，保留 7 天）。单条一到几分钟（长片更久）。多数模型按秒计费、少数按条计费（单价见上表），失败全额退。`size` 设画面比例（默认 `16:9` 横屏，`9:16` 竖屏）；图生视频在 `image` 里传参考图作为首帧。
```bash
# 1) 提交任务 -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"veo-3.1","prompt":"一只猫在日落时冲浪","size":"16:9","duration":"8s"}'
# 2) 轮询任务（每 5 秒一次，直到 status=succeeded，结果在 data[0].url）
curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
可用的视频模型：`veo-3.1`、`gemini-omni-1.2-flash`、`gemini-omni-flash`、`seedance-2.5-token`、`seedance-2.5-token-draft`、`seedance-2.5`、`seedance-2.5-flash`、`seedance-2.0`、`seedance-2.0-fast`、`seedance-2.0-mini`、`seedance-2.0-clip`、`seedance-2.5-30s`、`wan3.0-video`、`wan3.0-video-prime`、`minimax-h3`、`minimax-h3-lite`、`grok-imagine-video-1.5`。
公共参数：`size`（或 `aspect_ratio`）选方向，`duration` 选时长，`resolution` 选清晰度（仅部分模型支持），`image` / `images[]` 传参考图即图生视频（以图为首帧）。每个模型支持的时长与清晰度档位不同，逐模型的取值表在 `/docs/<模型 id>`，例如 [/docs/veo-3.1](/veo-3.1)。

## 原生 Anthropic 接口（Claude Code 直连）
Claude 模型除 OpenAI 兼容口径外，还提供**原生 Anthropic Messages API**。把 Claude Code 等工具的 `ANTHROPIC_BASE_URL` 指到 `https://kovapi.com/anthropic`、用网关 Key 作 `x-api-key`（也兼容 `Authorization: Bearer`）即可直连，thinking / 工具调用(tool_use) / 提示缓存(prompt caching) 等原生特性完整保留。可用模型：claude-opus-5、claude-fable-5、claude-sonnet-4-6。计费与 /v1 一致，按 token 计价（含缓存读写）。
```bash
export ANTHROPIC_BASE_URL=https://kovapi.com/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
curl https://kovapi.com/anthropic/v1/messages -H "x-api-key: YOUR_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" -d '{"model":"claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
```
同样支持 `"stream": true` 流式（标准 Anthropic SSE：message_start / content_block_delta / message_delta / message_stop）、`/anthropic/v1/messages/count_tokens` 与 `GET /anthropic/v1/models`。
**提示缓存计费**：缓存命中（缓存读）按输入价的 **1/10**（0.1×）计、缓存写入按 **1.25×** 输入价计（各模型具体单价见[价格页](https://kovapi.com/pricing)）。命中条件：① 前缀逐字节稳定 ② 前缀足够长（Claude Opus ≥ 4096 tokens、Sonnet ≥ 2048）③ 短时间内重复调用同一前缀。Claude Code 带大 `CLAUDE.md` / 系统提示跑真实代码库时通常每轮命中，输入成本降至约 1/10；在线测试台（Playground）的短问答因前缀过短不会命中缓存，属正常现象。

## 查询余额 (Balance)
用任意一个 API Key 即可查询本账户剩余额度与消费(无需登录后台):
```bash
curl https://kovapi.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```
OpenAI 兼容(余额 = `total_available`,可被各类余额查询工具自动识别):
```bash
curl https://kovapi.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## 错误码
| HTTP | 什么时候出现 |
| --- | --- |
| 400 | 参数有误或模型不存在（如 `model_not_found`），`error.param` 指出是哪个字段。 |
| 401 | 没带 Key，或 Key 无效、已停用（`missing_api_key`、`invalid_api_key`）。 |
| 402 | 余额不足，或这把 Key 达到了预算上限（`insufficient_quota`）。 |
| 403 | 这把 Key 的模型白名单里没有这个模型，或请求来自这把 Key 的 IP 白名单以外（`permission_denied`）。 |
| 404 | 路径不存在；或任务号不存在、超过了 3 天的保存期、不是这个账号提交的（`job_not_found`）。 |
| 429 | 超过了这把 Key 设置的每分钟请求数或免费模型的每日额度，或者这个模型暂时满载（`rate_limit_exceeded`）。有 `Retry-After` 头就按它等待，没有就等几秒再试。 |
| 502 | 上游出错或超时，自动重试后仍然失败；`code` 写明原因，如 `upstream_timeout`、`upstream_unavailable`。没有计费，可以重试。 |
| 503 | 模型维护中（`model_maintenance`），或我们这边临时出错（`service_unavailable`）。没有计费，稍后重试。 |

完整错误码列表: https://docs.kovapi.com/zh/guide/errors/md