計費

現金計價，不是點數

價格直接以美元標註：「每張圖 $0.008」「每輸出秒 $0.042」。預付資金、贈金與授信都以美元計量，但授信上限並不是現金餘額。

不用點數是刻意的：點數制會在「儲多少送多少」和「一點值多少錢」之間製造一層換算，讓你算不清真實成本。你看到的價就是你付的價。

// 顯示時保留原始十進位字串
const usd = task.cost;

from decimal import Decimal
usd = Decimal(task["cost"])   # 而不是 float()

查詢目前 API Key 的用量

curl 'https://api.spicyapi.ai/api/v1/usage?from=2026-09-01&to=2026-09-06' \
  -H "Authorization: Bearer $SPICY_API_KEY"

日期按 UTC 的左閉右開區間 [from,to) 解釋，上例包含9月1日至5日。省略日期時回傳最近7天（包含今天），最長92天。只回傳目前這把 Key 的任務，不提供其他 Key 或整個帳號的查詢參數；帳號餘額仍使用 chat/credit。

data.totalCalls 是全部任務數量，data.totalSpend 是已結算實收金額；days 與 models 分別按建立日和模型分組，金額都是 USD 十進位字串。未結算預扣不計入消費，遲到結算可能更新過去日期的金額。隱藏的歷史任務仍計入，沒有任務的日期不會補上一筆零值。兩個分組描述同一批任務，不要相加兩次。

SDK 使用 client.getUsage({ from, to })；CLI 使用 spicyapi usage --from 2026-09-01 --to 2026-09-06。不需要在每次生成前查詢用量或餘額，任務受理本身會執行餘額與預算檢查。

計費單位

一個模型只有一個計費單位。

欄位名不用猜：模型目錄介面的 quantityField 會逐模型告訴你，空字串表示按次計一單位。

同一個模型的不同級距可以有不同價格。影響價格的輸入可能包括解析度、時長、音訊選項或參考素材，具體以該模型 Schema 為準。pricing[].variant 是價卡的級距識別碼，請求本文裡沒有 variant 這個欄位。不要假設它總能直接當作 resolution，也不要只用「起價 × 時長」重新計算所有模型。將完整輸入傳送到 jobs/quote，使用回傳的精確估算與收費上限。

各模型的確切單位與價格見價格頁與各自的模型頁。

客戶折扣與促銷

優惠可以面向所有使用者，也可以僅適用於指定帳戶；範圍可以是全部模型或選定模型。長期優惠持續到停用，限時優惠只在真實的開始與結束時間之間生效。帳戶專屬優惠只在對應帳戶登入或使用其 API Key 報價時適用，不會成為其他使用者的公開價格。

優惠不疊加，自動採用你可享的最低價格。 例如標準費用為 $10，公開活動減免 10%、帳戶優惠減免 20%，適用價格為 $8，而不是連續打折後的 $7.20。活動結束或停用後，新報價重新選擇仍有效的優惠；其他優惠也沒有時恢復標準價。

首頁、目錄和模型頁的優惠展示供選擇模型時參考，實際費用請以攜帶身分、完整模型與輸入參數的 jobs/quote 為準。倒數計時不會鎖定價格；活動、輸入或價格變化後，請重新取得報價。任務受理後按當時凍結的價格結算，活動在執行中結束不會讓該任務漲價，最終收費也不會超過受理時的凍結金額。

優惠按 API 請求的消費金額自動套用，不會讓儲值本金打折，也不是儲值返現。按日或按月展示的預算只按目前價格外推；限時活動可能在預算週期結束前到期，請同時核對優惠結束時間。

贈金與授信

GET /api/v1/chat/credit 保留 available、held、total，並可回傳 funding 資金來源明細。舊回應可能沒有 funding，缺失不等於零。SDK 使用 client.getBalance()，CLI 使用 spicyapi balance --json；不必在每次生成前先查餘額。

• funding.prepaidAvailableUsd 是預付或歷史通用可用資金；grantAvailableUsd 是目前有效的贈金合計。每筆 grants 列出金額、可用、凍結、已用、狀態、生效與到期時間及 modelSlugs。模型列表為空表示全部模型；非空時只能支付對應模型的消費。列表最多回傳 100 筆，優先展示仍有餘額或凍結金額的批次，再按時間從新到舊排列。grantsHasMore 為真表示還有未回傳的記錄，不能用列表小計代替合計。
• funding.credit 是經批准的先用後付額度：limitUsd 為上限，availableUsd 為剩餘可用授信，usedUsd 為已結算欠款，heldUsd 為在途任務佔用，expiresAt 為到期時間。授信上限不是儲值、贈金或現金餘額。 到期、停用或超限會限制新呼叫，已有欠款仍須償還。
• 贈金不可提現。折扣決定請求售價，贈金與授信決定如何支付該售價；贈金不會降低模型價卡金額。贈金只在真實有效期及模型範圍內可用，未用部分可能到期或撤銷。任務失敗或少用時按原來源釋放；已到期或撤銷的贈金不會因此重新有效。
• funding.cashShortfallUsd 大於零表示外部付款追回造成的待補足資金缺口，贈金和授信不能抵補，補足前不能新建呼叫。available 為負也可能只是已批准授信的使用，因此不能單憑它斷言餘額不足，也不要把它與授信上限直接相加。伺服器端會在受理時檢查資金來源、模型範圍、有效期及消費上限。

所有金額仍為精確 USD 十進位字串，日期為 RFC3339；顯示時請註明時區。控制台帳單頁顯示資金與贈金明細，資金變更只有在管理員手動審核後才生效。需要贈金或授信時聯絡支援；公開 API 不提供自助增加額度或發放贈金的寫入介面。

三個階段

查餘額

GET /api/v1/chat/credit

curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

const res = await fetch('https://api.spicyapi.ai/api/v1/chat/credit', {
  headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` },
});
const body = await res.json();
if (body.code !== 200) throw new Error(`${body.code} ${body.msg}`);

const balance = body.data;
console.log(balance.funding ?? balance);

import os, requests

res = requests.get(
    "https://api.spicyapi.ai/api/v1/chat/credit",
    headers={"Authorization": f"Bearer {os.environ['SPICY_API_KEY']}"},
)
body = res.json()
if body["code"] != 200:
    raise RuntimeError(f'{body["code"]} {body["msg"]}')

balance = body["data"]
print(balance.get("funding", balance))

{
  "code": 200,
  "msg": "success",
  "data": {
    "available": "128.42",
    "held": "0.36",
    "total": "128.78"
  }
}

可用於該模型和時點的資金不足以覆蓋預估費用時，建任務回傳 40201。授信過期、額度用盡及需要補足的資金缺口也會影響受理資格；不要在用戶端用 available 的正負自行取代伺服器端的判斷。

消費上限

四層，任意一層觸頂都會拒絕新任務並回傳 40202：

日上限按 UTC 日期計算，零點重新起算；月上限按 UTC 自然月計算，每月 1 日零點重新起算。累計上限不會重置。

還沒結算的凍結不論落在哪一天、哪一個月，都仍然佔著日上限與月上限：錢還沒花掉，但也不能再花第二次。團隊自己的日／月預算是另一層，見Console 與團隊。

上限是保護你的，不是限制你。一個寫錯的迴圈在幾小時內燒掉一大筆錢，在這個行業裡是常見事故，而它幾乎總是發生在沒設上限的帳號上。

帳務明細

控制台的帳單頁會列出每一筆餘額變動。型別有這幾種：

贈送額與儲值本金分開記帳，是因為退款只退本金：贈送部分是我們的行銷成本，不是你的錢。

控制台帳單頁保留儲值、預扣、結算、退回和人工衝正等餘額變動，便於核對與爭議處理。它不受任務 input / output 30 天清理週期影響；我們目前不對所有帳務明細承諾一個統一、固定的公開保留年限。見資料留存。