模型目錄與 Schema

從已認證的即時目錄選擇可呼叫模型，並按目前 JSON Schema 建構請求。

createTask.model 必須使用已認證 GET /api/v1/models 回應回傳的精確 model 值。input 則由同一條目的目前 inputSchema 定義。只有該執行時回應能證明一個 ID 目前可呼叫。

不要從靜態頁面複製模型 ID

首發快照、系列頁和模型出品方目錄只用於發現能力，可能包含規劃中、已停用或已改名的條目。即時目錄為空時，不能拿這些靜態來源頂替。建立付費任務前必須讀取已認證目錄，並同時要求 enabled: true 與 available: true。

同時選擇模型與已驗證輸入

不同模型的請求 Schema 不同。可執行的安全路徑應從即時目錄裡把模型 ID 與伺服器端已驗證的範例輸入一起選出來：

const response = await fetch(
  'https://api.spicyapi.ai/api/v1/models?includeSchema=1&includeExamples=1',
  { headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` } },
);
const envelope = await response.json();
if (!response.ok || envelope.code !== 200) throw new Error(envelope.msg);

const selected = envelope.data.items.find(
  (item) => item.enabled && item.available && item.examples?.length,
);
if (!selected) throw new Error('No callable model with a validated example');

const createTaskBody = {
  model: selected.model,
  input: selected.examples[0].input,
};

當某個 inputSchema 暴露條件分支時，以根節點的 anyOf（各分支只含 required，「至少給一個」）與 allOf（if → then，「給了 A 就必須給 B」）確定欄位組合，不要憑模型系列猜測。不會出現 oneOf / not / dependentSchemas。新端點遵循 Spicy Schema 的 canonical fields；歷史端點以即時 Schema 為準。

程式化讀取目錄

GET /api/v1/models
GET /api/v1/models/{model}

curl "https://api.spicyapi.ai/api/v1/models?modality=video&includeSchema=1&includeExamples=1" \
  -H "Authorization: Bearer $SPICY_API_KEY"

參數	說明
`modality`	`image` `video` `audio` `text`
`provider`	精確模型出品方識別碼，只描述模型的作者或機構
`task`	精確任務，如 `image-to-video`
`search`	最長 128 字元
`includeSchema`	`true` / `1` 時帶回 `inputSchema`
`includeExamples`	`true` / `1` 時帶回已通過目前 Schema 驗證的範例

/models/{model} 裡的斜線屬於模型識別碼時，需按用戶端要求做 URL 編碼。

用戶端應讀的欄位

欄位	用途
`family`	穩定系列識別碼，用於頁面聚合
`tasks`	系列支援的任務集合
`inputSchema`	JSON Schema 2020-12，用於建構表單與驗證請求
`pricing` / `startingPrice`	此帳號目前的價格，金額為 USD 字串
`quantityField`	計費數量欄位；新影片端點通常為 `duration_seconds`，始終以目錄為準
`maxOutputDurationSeconds`	該模型能生成的最長輸出時長，取自 Schema 裡 `duration_seconds` 的 `maximum`；沒宣告上限時不回傳。它不是 `taskTimeoutSeconds`——後者是平台的執行逾時
`enabled`	目錄條目是否已允許 API 使用
`available`	目前是否存在可用 deployment
`examples`	已通過目前 Schema 驗證的輸入；僅在請求時回傳
`version` / `updatedAt`	目錄快取失效與變更追蹤

目錄回應可私有快取 60 秒，不要做公共 CDN 快取，因為價格包含帳號分組倍率。

Schema 與 Playground 的共同規則

inputSchema 使用 JSON Schema 2020-12。標準關鍵字決定伺服器端驗證；欄位內的 x-ui 物件只描述 Playground 的排序、顯示方式和重新報價提示。用戶端必須忽略未知的展示用擴充鍵，它們不能替代 required、enum、範圍或條件分支。完整規則見 Spicy Schema。

自己渲染逐模型的參數列

本站不提供逐模型的參數列。原因不是省事：模型與欄位每週都在變，任何靜態副本都會漂移，而讀到過期參數的代價是 400 或算錯價。參數只有一個來源，就是目錄回傳的 inputSchema——Playground 渲染的是同一份，SDK 驗證的也是同一份。

一份 Schema 裡各部分該顯示成什麼

Schema 裡的東西	參數列裡顯示成
`properties` 的鍵	參數名。欄位名跨模型統一，同一語義在所有模型裡都叫同一個名字
`required` 是否含該鍵	必填 / 選填
`anyOf` / `allOf`	條件必填。`anyOf` = 這幾個裡至少給一個；`allOf` 的 `if` → `then` = 給了 A 就必須給 B
`type`	型別
`description`	參數說明。它是英文散文，可以原樣展示，不需要你另寫一份
`enum`	允許的值。若同時有 `x-ui.enum_labels`，用它把取值翻成給人看的文字
`minimum` / `maximum`	取值區間；`x-ui.step` 是步進，`x-ui.unit` 是單位字尾（`s` / `px`）
`default`	預設值。不傳就是它
`x-ui.order`	排序依據，數值大的在前。不要按 `properties` 的鍵順序排，JSON 物件的鍵順序不是契約
`x-ui.primary`	置頂顯示的主輸入
`x-ui.advanced`	可以預設摺疊的進階參數
`x-ui.affects_price`	標一個「會改價格」的記號；改這個值需要重新報價
`x-ui.widget`	要做成可填的表單時，用它決定控制項（13 個取值見 Spicy Schema）

取資料

const res = await fetch(
  'https://api.spicyapi.ai/api/v1/models/seedance%2F2.5%2Fimage-to-video?includeSchema=1&includeExamples=1',
  { headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` } },
);
const { data } = await res.json();
const schema = data.inputSchema;

const rows = Object.entries(schema.properties)
  .sort(([, a], [, b]) => (b['x-ui']?.order ?? 0) - (a['x-ui']?.order ?? 0))
  .map(([name, prop]) => ({
    name,
    required: (schema.required ?? []).includes(name),
    type: prop.type,
    description: prop.description,
    values: prop.enum
      ? prop.enum.map((v) => prop['x-ui']?.enum_labels?.[v] ?? v)
      : prop.minimum !== undefined
        ? [`${prop.minimum}–${prop.maximum}${prop['x-ui']?.unit ?? ''}`]
        : [],
    default: prop.default,
    affectsPrice: prop['x-ui']?.affects_price === true,
    advanced: prop['x-ui']?.advanced === true,
  }));

includeExamples=1 會額外帶回 examples：每條都是伺服器端按目前 Schema 驗證過的完整輸入，可以直接當「最小可執行範例」貼進文件，也可以直接提交。比自己拼一個更安全——自己拼的範例會隨 Schema 變化而失效，examples 不會。

同一段程式碼換個 model 就能涵蓋任何模型，也不會因為我們上架新模型而過期。要一次產生全站參數列，把 GET /api/v1/models?includeSchema=1 的 items 迴圈一遍即可；目錄回應可私有快取 60 秒，並依 version / updatedAt 讓快取失效。