venice-api-overview

Venice API の概要

Venice.ai は、テキスト、画像、音声、動画、埋め込み、型付きの判定に対応した、OpenAI 互換の推論プラットフォームです。1 つの API で 2 つの支払い方法を利用できます。従来のAPI キー（Venice アカウント）か、ウォレット（x402、Base または Solana 上の USDC、アカウント不要）です。

次のような場合に使用します

• 初めて api.venice.ai を使ってコードを記述するとき。
• API キー認証と x402／ウォレット認証のどちらを使うか判断するとき。
• タスクごとに呼び出すエンドポイントをすぐに把握したいとき。
• 共通のレスポンスヘッダー（x-ratelimit-*、PAYMENT-REQUIRED、非推奨を示すヘッダーなど）を理解したいとき。

ベース URL

すべてのエンドポイントは次の配下にあります。

https://api.venice.ai/api/v1

OpenAPI 仕様は https://api.venice.ai/api/v1/swagger.yaml で提供されています（info.version は YYYYMMDD.HHMMSS 形式のタイムスタンプです。ライブ仕様から読み取ってください）。

認証

方式	ヘッダー	最適な用途
BearerAuth	Authorization: Bearer $VENICE_API_KEY	サーバーサイドアプリ、アカウント管理、使用状況の分析、DIEM／バンドルクレジット
siwx（x402）	SIGN-IN-WITH-X: <base64 SIWX JSON>（レガシーの X-Sign-In-With-X も受け付けます）	アカウント不要、Base または Solana 上の USDC による従量課金、サーバーレス／エージェント

すべてのエンドポイントが両方の方式を受け付けるわけではありません。

エンドポイント	受け付ける方式
すべての推論エンドポイント：chat、responses、embeddings、decisions、image、audio（speech、transcriptions、voices、queue/retrieve/complete、voice-changer queue/retrieve/complete）、video queue/retrieve/complete、augment、POST /crypto/rpc/{network}	Bearer または SIWX
/api_keys/*（generate_web3_key を除く）、/billing/*（廃止済みの /billing/usage を除く）、/characters/*	Bearer のみ（SIGN-IN-WITH-X ヘッダーのみの場合は 401 Authentication failed が返されます）
/x402/balance/{wallet}、/x402/transactions/{wallet}	SIWX のみ（署名者がウォレットを所有している必要があります）
/models*、/image/styles、/video/quote（topaz-video-upscale などのアップスケールモデルを除く。これらには Bearer キーが必要なため、ウォレットでは見積もりを取得できません）、/audio/quote、/audio/voice-changer/quote、/crypto/rpc/networks、/tee/attestation、/tee/signature、/api_keys/generate_web3_key、POST /x402/top-up	認証不要

Bearer のみのエンドポイントも含め、認証情報が必要なルートに Authorization ヘッダーも SIGN-IN-WITH-X ヘッダーも付けずにリクエストすると、401 ではなく、x402 の検出用本文（支払いオプション、SIWX チャレンジ、authOptions）を含む 402 が返されます。詳しくは venice-auth を参照してください。

# Bearer
curl https://api.venice.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"zai-org-glm-5-2","messages":[{"role":"user","content":"hi"}]}'

// x402 wallet via the SDK (EVM / Base wallets)
import { VeniceClient } from 'venice-x402-client'
const v = new VeniceClient(process.env.WALLET_KEY!)
await v.models()

エンドポイント一覧

推論

カテゴリ	エンドポイント	スキル
チャット	POST /chat/completions	venice-chat
Responses（アルファ版）	POST /responses	venice-responses
埋め込み	POST /embeddings	venice-embeddings
Decisions（ベータ版）	POST /decisions（エイリアス POST /systemone）	venice-decisions
画像生成	POST /image/generate, POST /images/generations, GET /image/styles	venice-image-generate
画像編集	POST /image/edit, POST /image/multi-edit, POST /image/upscale, POST /image/background-remove	venice-image-edit
TTS	POST /audio/speech, POST /audio/voices（音声クローン）	venice-audio-speech
STT	POST /audio/transcriptions	venice-audio-transcription
音楽／オーディオ（非同期）	POST /audio/quote, /audio/queue, /audio/retrieve, /audio/complete	venice-audio-music
ボイスチェンジャー（非同期）	POST /audio/voice-changer/quote, /queue, /retrieve, /complete	venice-audio-voice-changer
動画（非同期）	POST /video/quote, /video/queue, /video/retrieve, /video/complete	venice-video

ボイスチェンジャー：エンドポイントは仕様に含まれていますが、現在、公開されているボイスチェンジャーモデルはありません。まず GET /models?type=music で voice_changer: true のモデルを確認してください。

カタログ

カテゴリ	エンドポイント	スキル
モデル	GET /models, /models/traits, /models/compatibility_mapping	venice-models
キャラクター	GET /characters, /characters/{slug}, /characters/{slug}/reviews	venice-characters

GET /models?type= は text（デフォルト）、image、video、music、tts、asr、embedding、upscale、inpaint、decision に加え、フィルターの all と code を受け付けます。

アカウント、請求、ウォレット

カテゴリ	エンドポイント	スキル
API キー	GET/POST/PATCH/DELETE /api_keys, GET /api_keys/{id}, /api_keys/rate_limits, /api_keys/rate_limits/log, /api_keys/generate_web3_key	venice-api-keys
請求（ベータ版）	GET /billing/balance, /billing/usage-history, /billing/usage-analytics	venice-billing
x402 ウォレット	POST /x402/top-up, GET /x402/balance/{wallet}, GET /x402/transactions/{wallet}	venice-x402

ユーティリティ

カテゴリ	エンドポイント	スキル
暗号資産 RPC プロキシ	GET /crypto/rpc/networks, POST /crypto/rpc/{network}	venice-crypto-rpc
拡張	POST /augment/text-parser, /augment/scrape, /augment/search	venice-augment
TEE 検証	GET /tee/attestation, GET /tee/signature（公開、IP あたり 10 req/min）	venice-text-routing

廃止済み（410 Gone を返します）

エンドポイント	置き換え先
GET /billing/usage - 2026-09-16 に提供終了	GET /billing/usage-history（カーソルページネーション：pageSize + nextCursor、startTimestamp / endTimestamp）
POST /video/transcriptions	capabilities.supportsVideoInput が true のモデルで、video_url パートを指定した POST /chat/completions

どちらも 410 に加えて、Deprecation および Link: <…>; rel="successor-version" ヘッダーを返します（/billing/usage は Sunset も送信します）。認証は不要です。ポーリングを続けるクライアントには、IP あたり 1 分間に 60 リクエストの制限が適用され、429 が返されます。

確認すべきレスポンスヘッダー

ヘッダー	対象となる場合	意味
x-ratelimit-limit-requests / -remaining-requests / -reset-requests	ほとんどの推論レスポンス	アカウントのリクエスト枠です。モデルごと（分単位と日単位のうち、より厳しい方）、または動画・音声生成ルートと /augment/scrape / /augment/search ではエンドポイントごとに設定されます。リセット時刻は Unix タイムスタンプの ミリ秒 です。
x-ratelimit-limit-tokens / -remaining-tokens / -reset-tokens	トークン数に上限のあるテキストモデル	1 分あたりのトークン枠です（リセット時刻はミリ秒）。
x-ratelimit-remaining / x-ratelimit-resets	認証情報が必要なルートのほとんどのレスポンス	リクエストの上限ではなく、エラーバジェット（30 秒間に許可される失敗リクエスト数）です。現在のレスポンスがカウントされる前に読み取られるため、失敗レスポンスに 1 と表示されている場合、残りはありません。リセット時刻はミリ秒です。
x-venice-balance-usd / x-venice-balance-diem	推論レスポンス	リクエスト開始時点で使用可能な残高です（x402 の呼び出し元には、ウォレットのクレジット残高が表示されます）。残高がゼロの場合は省略されます。USD の数値には、バンドルクレジットと獲得したクレジットは含まれません。
x-venice-version	推論レスポンス	サーバーのリビジョンです。バグ報告に役立ちます。
x-venice-deprecated、x-venice-model-deprecation-date、x-venice-model-deprecation-warning、x-venice-deprecated-replacement	廃止予定モデルへのリクエスト（チャット、画像、動画キュー）	廃止日と推奨される代替モデルです。
PAYMENT-REQUIRED	すべての x402 402：認証情報がない場合、ウォレット残高が最低額を下回る場合、/x402/top-up の探索時、SIWX を使わずに /x402/balance / /x402/transactions を呼び出した場合	x402 v2 の支払い要求オブジェクト（accepts[] と、/x402/top-up を除き、sign-in-with-x チャレンジを含む）の Base64 JSON です。
Retry-After	429「モデルが過負荷です」	待機する秒数です（既定値は 30 秒）。
Deprecation / Sunset / Link	廃止されたエンドポイント	上の表を参照してください。
Content-Encoding	Accept-Encoding（gzip、br、deflate）を送信した場合	圧縮する価値があるサイズの本文を含む、すべてのルートの圧縮レスポンスです。仕様ではチャット、埋め込み、判定、画像生成について説明されています。

仕様では x402 レスポンスの X-Balance-Remaining ヘッダーについても説明されていますが、現在のサーバーコードでは設定されません。代わりに x-venice-balance-usd を確認するか、GET /x402/balance/{wallet} を呼び出してください。

料金モデルの概要

• 料金はリクエストごとに動的に設定され、USD で計算されます。仕様内の有料エンドポイントには x-payment-info ブロック（price.mode: dynamic、min: "0.001"、max: "10.00" USD）が含まれます。POST /x402/top-up の範囲は 5～10000 です。読み取り専用ルート（/models、見積もり）にはありません。
• API キーアカウントでは、各リクエストの料金が、DIEM → 獲得したクレジット → バンドルクレジット → USD の順に選択された単一の通貨で請求されます（venice-billing を参照）。キーごとの consumptionLimits では、USD / DIEM の支出に上限を設定できます。
• x402 ウォレットでは、Base または Solana でチャージしたプリペイドの USDC クレジット残高を使用します（最低チャージ額は $5、リクエストの開始には少なくとも $0.10 の残高が必要です）。DIEM をステーキングした Venice アカウントにリンクされた EVM ウォレットでは、最初に DIEM が使用されます。
• モデルごとの料金は GET /models → model_spec.pricing に記載されています。アカウントに適用中のプロモーションがすでに反映されています。動画の料金はここにはないため、POST /video/quote を使用してください。音楽 / ボイスチェンジャーの正確な見積もりは、/audio/quote と /audio/voice-changer/quote で取得できます。venice-models を参照してください。

標準的なエラー形式

ほとんどのエラーは次のとおりです。

{ "error": "Human-readable message" }

スキーマ検証の失敗（400）では、details ツリーと issues 配列が追加されます。

{ "error": "Invalid request parameters", "details": { "_errors": [], "type": { "_errors": ["Invalid enum value…"] } }, "issues": [ … ] }

知っておくべき例外として、チャットでコンテキスト長が上限を超えた場合は OpenAI 形式のオブジェクト（{ "error": { "message", "type": "invalid_request_error", "param": "messages", "code": "context_length_exceeded" } }）が返されます。上流プロバイダーによる拒否では、プロバイダーのメッセージが返されます（チャットなど、追跡対象のルートでは request_id も付加されます）。また、x402 の 402 では、チャージ用の構造化データが返されます。Content-Type が application/json でも multipart/form-data でもない POST は、認証処理の前に 400 と "'Content-Type' must be 'application/json'" を返します。全体の表と再試行方法については、venice-errors を参照してください。

OpenAI 互換性 — 対応する機能と対応しない機能

• そのまま使えるエンドポイント：/chat/completions、/responses、/embeddings、/images/generations、/audio/speech、/audio/transcriptions、/models。
• 互換性のために受け付けられますが、無視される項目：user、store（チャットの場合）。user は Venice の anon_user_id の別名ではありません（エラーバジェットの区分には使われます。詳しくは venice-errors を参照してください）。
• Venice 独自の拡張機能は venice_parameters の下にあります。/chat/completions では全項目が利用でき、/responses では 7 項目（character_slug、enable_e2ee、enable_web_search、enable_web_scraping、enable_web_citations、include_venice_system_prompt、include_search_results_in_stream）のサブセットが利用できます。
• モデル機能のサフィックス（例：zai-org-glm-5-1:enable_web_search=on、kimi-k2-6:strip_thinking_response=true&disable_thinking=true）をモデル ID に指定すると、venice_parameters を切り替えられます。詳しくは venice-chat を参照してください。
• 特性名（default_reasoning）や以前のエイリアス（gpt-4o）を model として送信できます。Venice が解決します。詳しくは venice-models を参照してください。

バージョン管理

• swagger.yaml の info.version はタイムスタンプ（YYYYMMDD.HHMMSS）です。/v2 はありません。機能は単一の /api/v1 インターフェイスで順次追加され、次の方法で管理されます。
  • エンドポイントの説明に付けられる Alpha/Beta ラベル（Responses は Alpha、Decisions と Billing は Beta）。
  • /models の betaModel／deprecation メタデータと機能フラグ。
• 廃止されたエンドポイントは、何も通知せずに消えるのではなく、Deprecation／Link ヘッダーを付けて 410 を返します。
• 機能を利用する前に、モデルの model_spec.capabilities（supportsWebSearch、supportsReasoning、supportsE2EE、supportsXSearch、supportsMultipleImages、supportsFunctionCalling、supportsAudioInput、supportsVideoInput、…）を必ず確認してください。

クイックスタートのチェックリスト

1. venice-auth を読み、Bearer と x402 のどちらを使うか選びます。
2. GET /models?type=… を実行し、モデルを選択して model_spec.constraints と model_spec.pricing を確認します。
3. 該当するスキルを参考に、正常系の呼び出しを 1 つ実装します。
4. venice-errors を使ってエラー処理を追加します（402、422、429）。
5. x-ratelimit-*／x-venice-balance-* ヘッダー、/billing/usage-history（ADMIN キーのみ）、または /x402/transactions/{wallet}（ウォレットからの呼び出し）を使って、オブザーバビリティを設定します。