# KovAPI API 개발자 문서

OpenAI 호환 AI API 게이트웨이. Base URL: `https://kovapi.com/v1`

## 인증
모든 요청에는 Bearer 토큰이 필요합니다:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 모델과 요금
| 모델 | 기능 | 엔드포인트 | 요금 |
| --- | --- | --- | --- |
| gpt-5.6-sol | 프런티어 추론, 에이전트 코딩, 장기 과제, 구조화 출력 | /chat/completions | 입력 $1.2/1M · 출력 $6.0/1M |
| gpt-5.6-luna | 고속 채팅, 에이전트 코딩, 대량 · 저지연 처리, 구조화 출력 | /chat/completions | 입력 $0.07/1M · 출력 $0.4/1M |
| gpt-6-astra | 심층 추론, 에이전트 코딩, 초장문 컨텍스트, 이미지 입력, 구조화 출력 | /chat/completions | 입력 $3.0/1M · 출력 $15.0/1M |
| gpt-6.1-sol | 에이전트 코딩, 복잡한 코딩, 전문 문서·분석 업무, 추론, 초장문 컨텍스트, 이미지 입력, 구조화 출력 | /chat/completions | 입력 $0.6/1M · 출력 $3.0/1M |
| gpt-6-sol | 복잡한 코딩, 에이전트 워크플로, 추론, 초장문 컨텍스트, 이미지 입력, 구조화 출력 | /chat/completions | 입력 $0.6/1M · 출력 $3.0/1M |
| gpt-6-luna | 대량 채팅, 저지연 에이전트 단계, 분류와 추출, 초장문 컨텍스트, 구조화 출력 | /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 |
| 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 |
| grok-imagine-image | 텍스트 기반 이미지 생성, 이미지 편집, 포스터, 제품 이미지, 소셜 비주얼, 중국어·영어 글자 | /images/generations | 1K $0.005 · 2K $0.005 |
| grok-imagine-image-quality | 커버, 포스터, 제품 이미지, 일러스트, 텍스트 기반 생성과 이미지 편집 | /images/generations | 1K $0.01 · 2K $0.01 |
| claude-sonnet-4-6 | 채팅, 코드, 추론, 긴 컨텍스트 | /chat/completions | 입력 $1.5/1M · 출력 $7.5/1M |
| claude-opus-5 | 심층 추론, 코드, 에이전트, 긴 컨텍스트, 이미지 이해 | /chat/completions | 입력 $4.0/1M · 출력 $20.0/1M |
| claude-fable-5 | 중국어 글쓰기, 서사 창작, 장문 생성, 채팅, 코드, 이미지 이해 | /chat/completions | 입력 $8.0/1M · 출력 $40.0/1M |
| claude-opus-5-5 | 복잡한 추론, 장시간 에이전트 코딩, 코드 엔지니어링, 도구 호출, 이미지와 PDF 이해 | /chat/completions | 입력 $2.5/1M · 출력 $12.5/1M |
| claude-sonnet-5-5 | 일상 코딩과 에이전트, 긴 컨텍스트, 도구 호출, 이미지와 PDF 이해, 대규모 프로덕션 트래픽 | /chat/completions | 입력 $1.5/1M · 출력 $7.5/1M |
| gemini-4-argon | Beta · 추론 · 긴 컨텍스트 | /chat/completions | 입력 $0.5/1M · 출력 $3.0/1M |
| gemini-3.1-pro | 채팅, 추론, 초장문 컨텍스트, 멀티모달 | /chat/completions | 입력 $0.5/1M · 출력 $3.0/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 |
| deepseek-v4-flash-0731 | 채팅, 추론, 코딩, 도구 호출, 사고 모드 전환, 버전 고정 | /chat/completions | 입력 $0.13/1M · 출력 $0.51/1M |
| glm-5.3 | 채팅, 코딩, 에이전트 워크플로, 추론, 중국어 · 영어 글쓰기, 도구 호출 | /chat/completions | 입력 $1.12/1M · 출력 $3.52/1M |
| qwen3.8-max | 추론, 코딩, 에이전트와 도구 호출, 중국어 · 영어 글쓰기, 이미지 이해 | /chat/completions | 입력 $1.4/1M · 출력 $4.2/1M |
| qwen3.8-flash | 대량 채팅, 분류와 추출, 요약과 재작성, 이미지 이해와 OCR, 도구 호출 | /chat/completions | 입력 $0.1/1M · 출력 $0.33/1M |
| grok-4.7 | 복잡한 추론, 코딩, 긴 문서 분석, 도구 호출, 구조화 출력, 이미지 이해 | /chat/completions | 입력 $0.3/1M · 출력 $0.9/1M |
| veo-3.1 | 짧은 영상, 제품 모션, 프레임 간 전환, 상업용 영상 | /videos/generations | $0.2 / 건 |
| gemini-omni-flash | 여러 컷의 짧은 영상, 콘티 기반 스토리, 프레임 간 전환 | /videos/generations | $0.05 / 초 (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.0 | 숏 클립, 상업용 소재 | /videos/generations | $0.15 / 초 (5–15초, 초 단위 과금) |
| seedance-2.0-fast | 대량 소재 제작, 빠른 콘셉트 확인 | /videos/generations | $0.075 / 초 (5–15초, 초 단위 과금) |
| seedance-2.0-mini | 대량 초안, 저비용 반복 작업 | /videos/generations | $0.046 / 초 (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.112 / 초 (4–30초, 초 단위 과금) |
| minimax-h3 | HD 영상, 소리가 있는 숏 클립 | /videos/generations | $0.036 / 초 (5–15초, 초 단위 과금) |
| grok-imagine-video-1.5 | 대량 숏폼, 빠른 콘셉트 확인 | /videos/generations | $0.3 / 건 |

## 채팅 (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"}]}'
```
이미지 입력(비전): `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) — 비동기 작업(제출하면 작업 ID를 돌려줍니다)
이미지 엔드포인트는 **작업(job) 방식만** 씁니다. 제출하면 즉시 `HTTP 202`와 작업 `id`가 돌아오고(`{"id":"img_...","object":"image.generation.job","status":"queued"}`), `GET /v1/images/jobs/{id}`를 `status`가 `succeeded`가 될 때까지 폴링한 뒤 `data[0].url`을 읽으면 됩니다(`img.kovapi.com` 링크로 15일간 보관되니 기한 전에 다운로드하거나 직접 운영하는 저장소로 옮겨 두세요). 제출 응답에 `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) status=succeeded가 될 때까지 2~3초 간격으로 폴링, 결과는 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) — 비동기 작업(제출하면 작업 ID를 돌려줍니다)
영상도 비동기 작업입니다. `POST /v1/videos/generations`를 호출하면 즉시 `HTTP 202`와 작업 ID가 돌아오고(`{"id":"img_...","object":"video.generation.job","status":"queued"}`), `GET /v1/videos/jobs/{id}`를 `status`가 `succeeded`가 될 때까지 폴링한 뒤 `data[0].url`을 읽으면 됩니다(재호스팅된 mp4 링크로 15일간 보관됩니다). 한 편에 1분에서 몇 분이 걸리며 긴 영상은 더 걸립니다. 대부분의 모델은 초 단위로, 일부는 건당 과금하며(단가는 위 표 참고) 실패 시 전액 환불합니다. `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) status=succeeded가 될 때까지 5초 간격으로 폴링, 결과는 data[0].url
curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
사용 가능한 영상 모델: `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`.
공통 파라미터: 방향은 `size`(또는 `aspect_ratio`), 길이는 `duration`, 화질은 `resolution`(지원하는 모델에 한함)으로 정하고, `image` / `images[]`에 참조 이미지를 넣으면 그 이미지를 첫 프레임으로 쓰는 이미지-투-비디오가 됩니다. 지원하는 길이와 해상도는 모델마다 다르며 모델별 표는 `/docs/<모델 id>`에 있습니다. 예: [/docs/veo-3.1](/veo-3.1).

## 네이티브 Anthropic API (Claude Code 직접 연결)
OpenAI 호환 경로 외에, Claude 모델은 **네이티브 Anthropic Messages API**로도 제공됩니다. Claude Code(또는 모든 Anthropic SDK)의 `ANTHROPIC_BASE_URL`을 `https://kovapi.com/anthropic`으로 두고 게이트웨이 키를 `x-api-key`로 쓰면 됩니다(`Authorization: Bearer`도 동작합니다). thinking, 도구 사용, 프롬프트 캐싱이 모두 그대로 통과합니다. 모델: claude-opus-5, claude-fable-5, claude-sonnet-4-6. 과금은 /v1과 완전히 같은 토큰 단위이며 캐시 읽기와 쓰기도 포함됩니다.
```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 토큰 이상, Sonnet 2048 이상), 그리고 짧은 시간 안의 반복 호출입니다. 큰 `CLAUDE.md`나 시스템 프롬프트를 들고 실제 코드베이스를 도는 Claude Code는 매 턴 적중해 입력 비용이 약 1/10로 줄고, 플레이그라운드의 짧은 대화는 접두부가 너무 짧아 캐시에 걸리지 않는 것이 정상입니다.

## 잔액 조회 (Balance)
아무 API 키로나 계정의 남은 잔액과 사용액을 조회할 수 있습니다. 대시보드 로그인이 필요 없습니다:
```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 | 키가 없거나, 유효하지 않거나, 정지된 키(`missing_api_key`, `invalid_api_key`). |
| 402 | 잔액이 부족하거나 키가 예산 한도에 도달했습니다(`insufficient_quota`). |
| 403 | 이 키의 모델 허용 목록에 해당 모델이 없거나, 키의 IP 허용 목록 밖에서 온 요청입니다(`permission_denied`). |
| 404 | 경로가 없거나, 작업 ID가 없거나 3일 기록 보관 기간이 지났거나 다른 계정이 제출한 작업입니다(`job_not_found`). |
| 429 | 이 키에 설정한 분당 요청 수나 무료 모델의 하루 한도를 넘었거나, 이 모델이 가득 찼습니다(`rate_limit_exceeded`). `Retry-After`가 있으면 그 초만큼, 없으면 몇 초 기다린 뒤 다시 시도하세요. |
| 502 | 업스트림 오류 또는 시간 초과로, 자동 재시도 후에도 실패했습니다. 이유는 `code`(`upstream_timeout`, `upstream_unavailable` 등)에 있습니다. 과금되지 않으니 다시 시도해도 됩니다. |
| 503 | 모델 점검 중(`model_maintenance`)이거나 당사 측의 일시적인 오류(`service_unavailable`)입니다. 과금되지 않으니 잠시 후 다시 시도하세요. |

전체 오류 코드 목록: https://docs.kovapi.com/ko/guide/errors/md