# KovAPI API developer docs

OpenAI-compatible AI API gateway. Base URL: `https://kovapi.com/v1`

## Authentication
Every request carries a Bearer token:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Models and pricing
| Model | Capability | Endpoint | Price |
| --- | --- | --- | --- |
| gpt-5.6-sol | Frontier reasoning, agentic coding, long-horizon tasks, structured output | /chat/completions | in $1.2/1M · out $6.0/1M |
| gpt-5.6-luna | High-speed chat, agentic coding, high-volume low-latency, structured output | /chat/completions | in $0.07/1M · out $0.4/1M |
| gpt-6-astra | Deep reasoning, agentic coding, very long context, image input, structured output | /chat/completions | in $3.0/1M · out $15.0/1M |
| gpt-6.1-sol | Agentic coding, complex coding, professional document and analysis work, reasoning, very long context, image input, structured output | /chat/completions | in $0.6/1M · out $3.0/1M |
| gpt-6-sol | Complex coding, agentic workflows, reasoning, very long context, image input, structured output | /chat/completions | in $0.6/1M · out $3.0/1M |
| gpt-6-luna | High-volume chat, low-latency agent steps, classification and extraction, very long context, structured output | /chat/completions | in $0.07/1M · out $0.4/1M |
| gpt-image-2 | Text-to-image, image-to-image, covers, posters, illustrations | /images/generations | 1K $0.005 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-flare | Text-to-image, image-to-image, covers, posters, illustration, typography | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 |
| gpt-image-2.5-sunburst | Text-to-image, image-to-image, covers, posters, illustration, typography | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 |
| nano-banana-2 | Text-to-image, image-to-image, covers, posters, illustrations | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-pro | Text-to-image, image-to-image, covers, posters, illustrations, infographics | /images/generations | 1K $0.02 · 2K $0.03 · 4K $0.05 |
| nano-banana-2.1 | Text-to-image, image editing, multi-image composition, posters and infographics, product shots, wide banners | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| grok-imagine-image | Text-to-image, image editing, posters, product shots, social visuals, Chinese and English lettering | /images/generations | 1K $0.005 · 2K $0.005 |
| grok-imagine-image-quality | Covers, posters, product shots, illustration, text-to-image and image editing | /images/generations | 1K $0.01 · 2K $0.01 |
| claude-sonnet-4-6 | Chat, code, reasoning, long context | /chat/completions | in $1.5/1M · out $7.5/1M |
| claude-opus-5 | Deep reasoning, code, agents, long context, image understanding | /chat/completions | in $4.0/1M · out $20.0/1M |
| claude-fable-5 | Chinese writing, narrative creation, long-form generation, chat, code, image understanding | /chat/completions | in $8.0/1M · out $40.0/1M |
| claude-opus-5-5 | Complex reasoning, long-horizon agentic coding, code engineering, tool calling, image and PDF understanding | /chat/completions | in $2.5/1M · out $12.5/1M |
| claude-sonnet-5-5 | Everyday coding and agents, long context, tool calling, image and PDF understanding, production traffic at scale | /chat/completions | in $1.5/1M · out $7.5/1M |
| gemini-4-argon | Beta · reasoning · long context | /chat/completions | in $0.5/1M · out $3.0/1M |
| gemini-3.1-pro | Chat, reasoning, very long context, multimodal | /chat/completions | in $0.5/1M · out $3.0/1M |
| gemini-3.8-flash | Chat, reasoning, adaptive thinking, image input, very long context | /chat/completions | in $0.6/1M · out $3.6/1M |
| deepseek-v4.1-flash | Chat, reasoning, coding, tool calling, switchable thinking mode | /chat/completions | in $0.075/1M · out $0.3/1M |
| deepseek-v4-flash-0731 | Chat, reasoning, coding, tool calling, switchable thinking mode, pinned version | /chat/completions | in $0.13/1M · out $0.51/1M |
| glm-5.3 | Chat, coding, agentic workflows, reasoning, Chinese and English writing, tool calling | /chat/completions | in $1.12/1M · out $3.52/1M |
| qwen3.8-max | Reasoning, coding, agents and tool calling, Chinese and English writing, image understanding | /chat/completions | in $1.4/1M · out $4.2/1M |
| qwen3.8-flash | High-volume chat, classification and extraction, summarising and rewriting, image understanding and OCR, tool calling | /chat/completions | in $0.1/1M · out $0.33/1M |
| grok-4.7 | Complex reasoning, coding, long-document analysis, tool calling, structured output, image understanding | /chat/completions | in $0.3/1M · out $0.9/1M |
| veo-3.1 | Short clips, product motion, first/last-frame transitions, commercial footage | /videos/generations | $0.2 / clip |
| gemini-omni-flash | Multi-shot clips, storyboard narratives, first/last-frame transitions | /videos/generations | $0.05 / s (6-10s, billed per second) |
| seedance-2.5-token | Text, image, video and audio references | /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 | Text, image, video and audio references | /videos/generations | USD / 1M video tokens: 480p draft $10.2 ($6.1 with reference video). Upgrade billed separately. |
| seedance-2.5 | Long-take short films, multi-reference input, commercial footage | /videos/generations | $0.158 / s (4-30s, billed per second) |
| seedance-2.0 | Short clips, commercial assets | /videos/generations | $0.15 / s (5-15s, billed per second) |
| seedance-2.0-fast | Bulk assets, quick concept checks | /videos/generations | $0.075 / s (5-15s, billed per second) |
| seedance-2.0-mini | High-volume drafts, low-cost iteration | /videos/generations | $0.046 / s (5-15s, billed per second) |
| seedance-2.0-clip | Short clips featuring real people, product videos, batch production | /videos/generations | $1.0 / clip |
| seedance-2.5-30s | Long-take storytelling, long-form product videos | /videos/generations | $2.0 / clip |
| wan3.0-video | Long-take storytelling, multi-asset composition, video rewriting | /videos/generations | $0.065 / s (4-30s, billed per second) |
| wan3.0-video-prime | Deadline footage, batch test shoots | /videos/generations | $0.112 / s (4-30s, billed per second) |
| minimax-h3 | HD footage, short clips with sound | /videos/generations | $0.036 / s (5-15s, billed per second) |
| grok-imagine-video-1.5 | Bulk short videos, quick concept checks | /videos/generations | $0.3 / clip |

## Chat (Chat Completions)
`POST /v1/chat/completions`, with `stream: true` for streaming output.
```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"}]}'
```
Image input (vision): put an `image_url` in the `content` array of `messages` -- a public image link or a 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":"What is in this picture?"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}]}'
```

## Images — async jobs (submitting returns a job id)
The image endpoints are **job-only**: submitting returns `HTTP 202` and a job `id` right away (`{"id":"img_...","object":"image.generation.job","status":"queued"}`); poll `GET /v1/images/jobs/{id}` until `status` is `succeeded` and read `data[0].url` (an `img.kovapi.com` link kept for 15 days; download it or copy it to your own storage). Do **not** expect `data` on the submit response.
**Text-to-image** is `POST /v1/images/generations`. **Image-to-image** is `POST /v1/images/edits`, or add `image` to generations -- the two are equivalent; `image` takes a public URL, a `data:` URI or base64.
```bash
# 1) submit -> 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) poll every 2-3s until status=succeeded, result in data[0].url
curl https://kovapi.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
For `size`, pass an aspect ratio -- `1:1` / `3:4` / `2:3` / `9:16` / `4:3` / `3:2` / `16:9` -- and the model renders **natively** at that ratio with no subject cropping; pixel sizes (`1024x1024` / `1024x1536` / `1536x1024`) are accepted too. Both text-to-image and image-to-image support it. The `async` field is no longer needed and is ignored if sent.


## Videos — async jobs (submitting returns a job id)
Video is a job too: `POST /v1/videos/generations` returns `HTTP 202` and a job id immediately (`{"id":"img_...","object":"video.generation.job","status":"queued"}`); poll `GET /v1/videos/jobs/{id}` until `status` is `succeeded` and read `data[0].url` (a re-hosted mp4 link kept for 15 days). A clip takes one to a few minutes (long clips longer). Most models bill per second of video and a few per clip -- the table above has each rate; a failed job is refunded in full. `size` sets the aspect ratio (`16:9` landscape by default, `9:16` portrait); for image-to-video pass a first-frame reference in `image`.
```bash
# 1) submit -> 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":"a cat surfing at sunset","size":"16:9","duration":"8s"}'
# 2) poll every 5s until status=succeeded, result in data[0].url
curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
Video models available: `veo-3.1`, `gemini-omni-flash`, `seedance-2.5-token`, `seedance-2.5-token-draft`, `seedance-2.5`, `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`, `grok-imagine-video-1.5`.
Shared parameters: `size` (or `aspect_ratio`) for orientation, `duration` for length, `resolution` for quality where the model supports it, and `image` / `images[]` for a reference frame, which makes it image-to-video. Supported durations and resolutions differ per model; the exact table for each is at `/docs/<model id>`, e.g. [/docs/veo-3.1](/veo-3.1).

## Native Anthropic API (Claude Code connects directly)
Beyond the OpenAI-compatible route, Claude models also expose the **native Anthropic Messages API**. Point `ANTHROPIC_BASE_URL` in Claude Code (or any Anthropic SDK) at `https://kovapi.com/anthropic` and use your gateway key as `x-api-key` (`Authorization: Bearer` works too). Thinking, tool use and prompt caching all pass through unchanged. Models: claude-opus-5, claude-fable-5, claude-sonnet-4-6. Billed exactly like /v1, per token, cache reads and writes included.
```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` is supported as standard Anthropic SSE (message_start / content_block_delta / message_delta / message_stop), along with `/anthropic/v1/messages/count_tokens` and `GET /anthropic/v1/models`.
**Prompt-cache billing**: a cache hit (cache read) bills at **1/10** of the input rate (0.1x) and a cache write at **1.25x** (per-model rates on the [pricing page](https://kovapi.com/pricing)). A hit needs three things: a byte-identical prefix, a long enough one (Claude Opus >= 4096 tokens, Sonnet >= 2048), and the same prefix repeated within a short window. Claude Code with a large `CLAUDE.md` or system prompt over a real codebase hits every turn and pays about a tenth for input; the short exchanges in the Playground are too small to cache, which is expected.

## Check your balance
Any API key can read the account balance and spend -- no dashboard login needed:
```bash
curl https://kovapi.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```
OpenAI-compatible (balance = `total_available`, so the usual balance-checking tools pick it up automatically):
```bash
curl https://kovapi.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## Error codes
| HTTP | When you see it |
| --- | --- |
| 400 | A bad parameter or an unknown model (such as `model_not_found`); `error.param` names the field. |
| 401 | No key, or the key is invalid or disabled (`missing_api_key`, `invalid_api_key`). |
| 402 | Not enough balance, or the key has reached its budget (`insufficient_quota`). |
| 403 | The model is not on this key's model allowlist, or the request comes from outside the key's IP allowlist (`permission_denied`). |
| 404 | The path does not exist; or the job id is unknown, past its 3-day record, or was submitted by another account (`job_not_found`). |
| 429 | Over the per-minute limit set on this key or a free model's daily quota, or the model is at capacity (`rate_limit_exceeded`). Wait the seconds in `Retry-After` when it is there, otherwise a few seconds, then retry. |
| 502 | The upstream failed or timed out and the automatic retries did not help; `code` says why, e.g. `upstream_timeout` or `upstream_unavailable`. Not billed; safe to retry. |
| 503 | The model is under maintenance (`model_maintenance`), or something failed on our side for a moment (`service_unavailable`). Not billed; retry later. |

Full list of error codes: https://docs.kovapi.com/en/guide/errors/md