見積もりとプロトコル互換

特定のリクエストを見積もる

見積もりは、1 つの具体的なリクエストの価格を、支払う前に教えてくれるものです。見積もりは無料で、タスクは作成されず、資金も仮押さえされません。そのあと見積もりを付けて同じリクエストを送信すると、そのリクエストは表示された価格でしか受理されません。

以下のコマンドは macOS または Linux のターミナル向けで、クイックスタートの説明どおりに SPICY_API_KEY が設定されていることを前提にしています。MODEL_ID_FROM_CATALOG は仮の値です。ライブカタログ（GET /api/v1/models）にある model の値を使い、input のフィールドはすべてそのモデルのスキーマに従って書いてください。

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" }
}

curl https://api.spicyapi.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "QUOTE_ID_FROM_RESPONSE",
    "model": "MODEL_ID_FROM_CATALOG",
    "estimatedCost": "0.008",
    "maxCharge": "0.008",
    "currency": "USD",
    "quantity": "1",
    "unit": "per_image",
    "expiresAt": "2026-09-17T10:05:00Z"
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" },
  "quoteId": "QUOTE_ID_FROM_RESPONSE",
  "expectedCost": "0.008"
}

SPICY_IDEMPOTENCY_KEY="$(uuidgen)"   # 新しいタスクごとに 1 回だけ作る。再利用するのは、このリクエストをそのまま送り直すときだけ

curl https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  --data-binary @submit.json

ネイティブのテキストストリームである POST /api/v1/jobs/stream も、同じ方法で見積もりを受け付けます。テキストとストリーミングを参照してください。

応答を受け取れなかったときの復旧

送信がタイムアウトしたり接続が切れたりすると、リクエストが受理されたかどうかがわかりません。createTask、retry、POST /v1/videos の場合は、次のようにしてください。

1. 元のリクエストを、元の Idempotency-Key を付けて、同じ API キーで送り直します。元のタスクが現在の状態で返ってきて、二重に課金されることはありません。
2. 新しいキーで別のタスクを作らないでください。新しいキーは、新しい生成と新しい課金を意味します。
3. すでに受理されたリクエストの再送は、見積もりの期限が切れたあとも有効です。期限が制限するのは受理であって、受理によって作られたタスクではありません。
4. 409 は「作成されなかった」という意味ではありません。リクエストが変わった（新しいキーが必要な、別の作業です）か、同じアカウントの別の API キーで送られた（元のキーで送り直してください）かのどちらかです。冪等性を参照してください。
5. 最終的な課金額は、recordInfo の cost と settled で確認します。

公式ツールでの見積もり

CLI と MCP サーバーは、課金されるすべての呼び出しの前に見積もりを取り、人に確認を求めます。そのため、このステップを自分で作る必要はありません。

• CLI： spicyapi tasks quote はリクエストの価格を計算します。spicyapi tasks create はもう一度見積もりを取り、金額を表示して、作成する前に確認を求めます。費用・確認・安全性を参照してください。
• MCP： アシスタントは自由に見積もりを取れますが、タスクを作成するときは、AI クライアントを通じて価格とともにあなたに確認を求めます。費用・確認・安全性を参照してください。
• SDK： quoteTask は見積もりを返します。その quoteId と estimatedCost を createTask か run に渡してください。

テキストと動画の互換 API

SpicyAPI は、テキストモデル向けに OpenAI・Anthropic・Google Gemini の形式を、動画向けに OpenAI Videos の形式も受け付けます。エンドポイントの一覧は API リファレンスに、プロトコルごとのリクエスト・ストリーム・エラーはテキストとストリーミングにまとめています。

ベース URL。 OpenAI 形式では https://api.spicyapi.ai/v1 を使います。Anthropic と Google GenAI の SDK は /v1 や /v1beta を自分で付け足すので、これらのベース URL は https://api.spicyapi.ai にします。

認証情報。 どの形式でも 1 つの API キーを使い、Authorization: Bearer ヘッダーに入れて送ります。Anthropic SDK が使う x-api-key ヘッダーと、Google GenAI SDK が使う x-goog-api-key ヘッダーも受け付けます。URL に付けた ?key= は、どの場合も受け付けません。

モデル。 ライブカタログから正確なモデルを選びます。ツール、画像を含むメッセージ、生成オプションが使えるかどうかは、選んだプロトコルではなく、そのモデルのスキーマで決まります。

応答の形。 各プロトコルは、プラットフォーム共通の {code, msg, data, request_id} という外枠ではなく、それぞれ独自の外枠で応答を返します。

推論フィールド

推論テキストを出力するチャットモデルは、message.reasoning_content（ストリーミング時は delta.reasoning_content）に、省略されることもある文字列を返す場合があります。ツール呼び出しのあとで会話を続けるときは、ライブのモデルスキーマが対応していれば、対応するアシスタントメッセージにこの値を残しておけます。

usage.completion_tokens_details.reasoning_tokens は、completion_tokens にすでに含まれている推論部分の量を表します。もう一度足さないでください。推論テキストやこれらのトークン内訳を返さないモデルもあります。

組み込む前に知っておきたい 2 つの形式

• Responses では、会話全体を input に入れる必要があります。previous_response_id には対応していません。
• Videos は、model、prompt、input_reference、seconds、size を含む JSON を受け付け、これらをモデル自身のフィールドに対応付けます。返ってくる動画の id はタスク ID でもあり、recordInfo にそのまま渡せます。コンテンツ取得用のエンドポイントは、HTTP 302 で、有効期間の短い署名付き URL にリダイレクトします。

公式の OpenAI・Anthropic・Google クライアントでチャットをストリーミングする例は、公式 SDK を使うを参照してください。CLI と MCP サーバーはネイティブのタスクを送信して追跡するもので、チャットのトークンをストリーミングすることはありません。