報價與協定相容

把按即時模型 Schema 填好的完整請求儲存到 request.json，其中包含 model、input 和選填的 callBackUrl。報價不會建立任務或凍結餘額，報價與主體、模型和這份請求繫結，有效期 5 分鐘。

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

estimatedCost、maxCharge 和 quantity 都是十進位字串；currency 固定為 USD。向使用者顯示金額、收費上限和 expiresAt，確認後用同一份請求提交 quoteId 與 expectedCost。輸入改變、報價過期或價格變化時，新受理回傳 40901，需要重新報價並確認。

網路中斷後重複使用原 Idempotency-Key 取回受理結果，不要產生新鍵重複建立。已受理的冪等重放不會因為報價隨後過期而失敗。最終費用看 recordInfo 的 cost 與 settled，不能把估算或文字串流的結束標記當成結算。

SDK、CLI 與 MCP

CLI tasks create 會先報價再確認；非互動環境必須明確加上 --yes。MCP spicyapi_task_quote 只報價，spicyapi_task_create 將精確報價寫入帶簽章的請求狀態，並透過協定詢問使用者；代理不能替使用者自動確認。

spicyapi tasks quote --model "$SPICY_MODEL" --input-file input.json
spicyapi tasks create --model "$SPICY_MODEL" --input-file input.json \
  --idempotency-key "$SPICY_IDEMPOTENCY_KEY" --wait

OpenAI 格式的 Base URL 是 https://api.spicyapi.ai/v1；Anthropic 與 Google GenAI SDK 的 Base URL 填 https://api.spicyapi.ai，它們會自己補上 /v1 或 /v1beta。所有相容介面使用同一 API Key：放在 Authorization: Bearer 標頭；Anthropic SDK 用的 x-api-key 和 Google GenAI SDK 用的 x-goog-api-key 也接受；網址裡的 ?key= 不接受。從即時目錄選擇支援 chat 的精確模型；工具呼叫、影像訊息和生成參數依模型 Schema 而定。回應遵循相應協定，沒有平台 JSON 外殼。各協定的參數對應、串流的結束方式與錯誤形狀見文字模型與串流。

協定	入口
Models	`GET /v1/models`
Chat Completions	`POST /v1/chat/completions`
Responses	`POST /v1/responses`
Messages	`POST /v1/messages`
Gemini generateContent	`POST /v1beta/models/{model}:generateContent`
Gemini streamGenerateContent	`POST /v1beta/models/{model}:streamGenerateContent`
Videos	`POST /v1/videos`
Video status	`GET /v1/videos/{videoId}`
Video content	`GET /v1/videos/{videoId}/content`

支援回傳推理文字的 Chat 模型可能提供 message.reasoning_content；串流回應則對應 delta.reasoning_content，該欄位為字串，不一定出現。工具呼叫後繼續對話時，可在對應的 assistant 訊息中原樣保留該欄位，是否支援以即時模型 Schema 為準。usage.completion_tokens_details.reasoning_tokens 僅說明輸出 token 中的推理部分，已包含在 completion_tokens 內，不能重複相加。並非所有模型都回傳推理文字或 token 明細。

Responses 需要在 input 中傳送完整對話；不支援 previous_response_id。Videos 使用 JSON 請求，接受 model、prompt、input_reference、seconds、size 等對應欄位；下載端點以 302 轉址到短期簽章網址。完整欄位與狀態見 OpenAPI。

報價憑證 quoteId 和 expectedCost 適用於 jobs/createTask 與 jobs/stream。/v1 與 /v1beta 相容介面按受理時價格執行；需要確認金額上限的流程請使用原生任務介面。

OpenAPI · API

使用官方 OpenAI 用戶端接收串流

Chat Completions 直接使用官方 openai 用戶端；@spicyapi/sdk 負責原生任務、報價和上傳。請另行安裝 openai。範例在你自己的伺服器端執行，使用目前可呼叫的精確對話模型 ID，並為每個使用者動作持久儲存一個冪等鍵。

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SPICY_API_KEY,
  baseURL: "https://api.spicyapi.ai/v1",
  maxRetries: 0,
});
const signal = AbortSignal.timeout(120_000);
const stream = await client.chat.completions.create({
  model: process.env.SPICY_MODEL,
  messages: [{ role: "user", content: "Explain a rainbow in one sentence." }],
  stream: true,
  stream_options: { include_usage: true },
}, {
  signal,
  headers: { "Idempotency-Key": process.env.SPICY_IDEMPOTENCY_KEY },
});
try {
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta.content ?? "");
    if (chunk.usage) process.stderr.write(JSON.stringify(chunk.usage) + "\n");
  }
} finally {
  stream.controller.abort();
}

終止訊號涵蓋連線與整個串流的讀取。中斷只停止本機接收，不取消已受理任務，也不承諾退款。非串流請求設定 stream: false，讀取 choices[0].message.content。工具對話按 index 拼接 tool call 片段，先保留完整 assistant 訊息，再新增對應 tool_call_id 的結果；僅在模型 schema 支援時啟用工具或推理欄位。

CLI 與 MCP 目前負責原生任務提交和追蹤，沒有逐 token 串流輸出的對話介面。即時聊天介面使用此用戶端；需要報價確認時使用原生 jobs/stream。

報價與協定相容

SDK、CLI 與 MCP

文字和影片相容介面

使用官方 OpenAI 用戶端接收串流

本頁目錄