# 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 | テキストからの画像生成、画像編集、ポスター、商品画像、SNS 用ビジュアル、中国語と英語の文字 | /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 | 高精細な映像、音声付きの短編クリップ | /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"}}]}]}'
```

## 画像生成 — 非同期ジョブ（送信するとジョブ ID が返ります）
画像エンドポイントは**ジョブ方式のみ**です。送信すると即座に `HTTP 202` とジョブ `id` が返り（`{"id":"img_...","object":"image.generation.job","status":"queued"}`）、`GET /v1/images/jobs/{id}` を `status` が `succeeded` になるまでポーリングして `data[0].url` を読みます（15 日間保存される `img.kovapi.com` のリンクです。期限までにダウンロードするか、ご自身のストレージに保存してください）。送信時のレスポンスに `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` フィールドはもう不要で、送っても無視されます。


## 動画生成 — 非同期ジョブ（送信するとジョブ 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 本あたり 1 分から数分（長い動画はそれ以上）かかります。多くのモデルは秒単位、一部は 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.1x）、キャッシュ書き込みは **1.25x** で課金します（モデルごとの単価は[料金ページ](https://kovapi.com/pricing)をご覧ください）。ヒットには 3 つの条件が要ります。バイト単位で同一の接頭部、十分な長さ（Claude Opus は 4096 トークン以上、Sonnet は 2048 以上）、そして短い間隔での繰り返しです。大きな `CLAUDE.md` やシステムプロンプトを抱えた Claude Code で実際のコードベースを扱うと毎ターンヒットし、入力コストは約 10 分の 1 になります。プレイグラウンドの短いやり取りは短すぎてキャッシュされませんが、それが正常です。

## 残高の確認
どの 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 | このキーに設定した 1 分あたりの上限か無料モデルの 1 日の枠を超えたか、このモデルが混み合っています（`rate_limit_exceeded`）。`Retry-After` があればその秒数、なければ数秒待ってから再試行してください。 |
| 502 | 上流のエラーまたはタイムアウトで、自動の再試行でも失敗しました。理由は `code`（`upstream_timeout`、`upstream_unavailable` など）に入ります。課金されないので、そのまま再試行できます。 |
| 503 | モデルのメンテナンス中（`model_maintenance`）、または当サイト側の一時的なエラー（`service_unavailable`）です。課金されないので、しばらくして再試行してください。 |

エラーコードの完全な一覧: https://docs.kovapi.com/ja/guide/errors/md