OpenAPI とエンドポイント一覧
ダウンロードできる OpenAPI 3.1 契約、全公開エンドポイントと説明ガイド、共通リクエストヘッダー、本番の接続先を紹介します。
機械で読める公開契約は OpenAPI 3.1 YAML として提供しています。クライアントの生成や、現在の公開エンドポイントとの連携検証に使えます。
本番 API の接続先
OpenAPI の servers[0].url に定義された本番接続先は https://api.spicyapi.ai だけです。タスク API は /api/v1、互換プロトコルは /v1 と /v1beta を使います。
これらの API で、コンソールを開かずモデルの選択、見積もり、支出の確認ができます。カタログにはアカウント料金があり、パラメーターで価格が変わる場合は正確な入力で見積もります。履歴と使用量の範囲は、呼び出す API キーです。キーの作成、交換、予算設定はコンソールで行います。各表から、詳しく説明するガイドへリンクしています。
モデルの検索、料金、アカウントの API
| メソッド | パス | 目的 | ガイド |
|---|---|---|---|
GET | /console/v1/catalog/models | 評価用の公開カタログ。キー不要、標準料金、接続元アドレスでレート制限 | クイックスタート |
GET | /api/v1/models | 呼び出せるモデル、アカウント料金、任意のスキーマを取得 | モデルカタログ |
GET | /api/v1/models/{model} | 1 モデルと完全な JSON Schema を取得 | モデルカタログ |
POST | /api/v1/jobs/quote | タスク作成や資金予約なしに、正確な要求を 5 分間有効な価格で見積もる | 見積もり |
GET | /api/v1/chat/credit | 利用可能額、予約額、総残高を取得 | 課金 |
GET | /api/v1/usage | 現在のキーの呼び出しと精算済み USD 支出を、日付・モデル別に取得 | 課金 |
生成とタスクの API
| メソッド | パス | 目的 | ガイド |
|---|---|---|---|
GET | /api/v1/jobs | 現在の API キーの履歴を、カーソル付きページ分割で取得 | タスク |
POST | /api/v1/jobs/createTask | 非同期の生成タスクを作成 | タスク |
GET | /api/v1/jobs/recordInfo | 呼び出す API キーで作成したタスクを取得 | タスク |
POST | /api/v1/jobs/retry | 失敗・期限切れタスクから新規作成。過去のキャンセル記録にも対応 | タスク操作 |
POST | /api/v1/jobs/purge | 終端タスク 1 件の生成物とプロンプトを破棄。請求記録は残す | 保持 |
POST | /api/v1/jobs/stream | テキストモデルを実行し、SSE で回答を配信 | テキストとストリーミング |
メディアの API
| メソッド | パス | 目的 | ガイド |
|---|---|---|---|
POST | /api/v1/common/upload-url | 直接アップロード用のチケットを発行 | メディア |
POST | /api/v1/files/{fileId}/commit | 直接アップロードを検証・確定し、タスクで使える spicy:// URI を返す | メディア |
POST | /api/v1/files/import | リンクから LoRA の重みファイルをインポートし、タスクで使える spicy:// URI を返す（アクセストークンは任意、1 回だけ使用し保存しない） | アダプターの重み |
POST | /api/v1/common/download-url | 短期の出力ダウンロード URL を発行。完了タスクに含まれるため任意 | メディア |
POST | /api/v1/assets | ファイルをアセットライブラリに保存（Idempotency-Key 必須） | メディア |
GET | /api/v1/assets | 保存済みアセットを一覧（favorite・collectionId・q で絞り込み、sort で並べ替え） | メディア |
GET | /api/v1/assets/usage | アセットライブラリのプラン、使用量、上限を取得 | メディア |
GET | /api/v1/assets/{assetId} | アセット 1 件を新しい非公開プレビューリンク付きで取得 | メディア |
PATCH | /api/v1/assets/{assetId} | アセット名または favorite フラグを変更 | メディア |
DELETE | /api/v1/assets/{assetId} | アセットを削除 | メディア |
GET | /api/v1/assets/entities | アセットライブラリのキャラクターを一覧（読み取り専用） | メディア |
GET | /api/v1/assets/entities/{entityId} | キャラクター 1 人を、画像を順番どおりに付けて取得（読み取り専用） | メディア |
認証と応答の外枠
公開カタログ以外には Authorization: Bearer sk-spicy-… のキーが必要です。互換エンドポイント（/v1、/v1beta）では、Anthropic SDK の x-api-key と Google GenAI SDK の x-goog-api-key も使えます。URL のクエリにキーを入れる方式は受け付けません。タスク、再試行、破棄、ダウンロードリンクは作成したキーだけから見えます。認証を参照してください。
タスク API の JSON は共通の {code,msg,data,request_id} の外枠を使い、互換エンドポイントは各プロトコルの形式を使います。タスクの結果は外枠の code ではなく data.state にあります。エラーを参照します。
エンドポイント共通のリクエストヘッダー
| ヘッダー | 送信先 | 目的 |
|---|---|---|
Authorization: Bearer … | 公開カタログ以外 | API キー |
Idempotency-Key | jobs/createTask、jobs/retry、jobs/stream、POST /v1/videos、/v1・/v1beta のテキストエンドポイント | ネットワークエラー後の安全な再送。タスクでは元を返し、テキストでは二重課金を防ぐが失った回答は返せない。冪等性参照 |
X-Spicy-Retention | jobs/createTask、jobs/stream | このタスクの出力とプロンプトの保持期間を秒で短縮。保持参照 |
Accept-Language | すべて | エラーメッセージの言語。コードは変わらない。エラー参照 |
OpenAPI ファイルを使う
- コードなしで要求を試す： 上部の OpenAPI を Postman、Insomnia、Bruno などへインポートし、Bearer トークンにキーを設定します。タスクの作成には費用がかかります。
- クライアントを生成する： 同じファイルを、その言語の OpenAPI 3.1 コード生成ツールへ渡します。
契約の変更
- モデルのパラメーターを固定の永久スナップショットにせず、
/models/{model}からinputSchemaを取得します。 - 未知の応答項目には対応できるようにしますが、未知の入力項目は推測しません。
- リリース前に OpenAPI YAML をコード生成や契約テストへ渡します。
互換エンドポイント
| メソッド | パス | プロトコル |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | 動画の状態 |
GET | /v1/videos/{videoId}/content | 動画の内容 |
テキストはテキストとストリーミング、料金は見積もりと互換性で説明しています。
公式の TypeScript パッケージは @spicyapi/sdk です。Python、Go、依存を追加できない場合は、下のコピー可能な参照クライアントが、言語の実行環境だけで呼び出します。Python はメディアタスク全体に対応します。参照のアップロードと確定、見積もり、作成、終端までのポーリング、ファイル・テキストの結果取得、期限切れリンクの更新、保存内容の破棄、Webhook 署名の検証です。Go も同じ工程に対応し、各呼び出しの context と errors.As で取得できる型付きエラーがあります。TypeScript は作成、再試行、状態取得、上限付き待機を扱います。Node.js のアップロードや残りの機能には SDK を使います。
コピー可能な参照クライアント
モデル検索、タスク作成、失敗したタスクの再試行、状態取得、全終端状態、上限付き待機、冪等性、エラー処理を含む依存なしの例です。受理済みのタスクは取り消せません。
文書内の例であり、npm・PyPI・Go モジュールとして公開されたものではありません。10 分はローカル上限で、SLA ではありません。
