Spicy Schema 契約

Spicy Schema は、新しいすべてのメディアモデルの公開契約です。追加で変わるのは model、inputSchema、利用者向け料金で、認証、タスク、結果、エラー、ダウンロードは共通です。

参照用のページです。多くの連携はモデルカタログとスキーマだけで足ります。inputSchema からフォーム、検証、コード生成を作り、何を前提にできるか詳しく知りたい場合に読んでください。

公開範囲

公開 ID は <publisher>/<model>/<task> という安定した 1 能力を表します。publisher は作者や研究組織などモデルの開発元です。画像編集の末尾は edit で、以前公開した識別子も引き続き受け付けます。必ずライブカタログから実 ID をコピーします。このページの MODEL_ID_FROM_CATALOG は仮の値です。

公開応答、Webhook、エラー、ダウンロードは、SpicyAPI 自身の識別子、エラーコード、URL だけを使います。内部処理、未加工の応答やエラー、内部の事業データを含みません。結果は返す前に SpicyAPI の保存先へコピーします。

共通の作成形式

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": {
    "prompt": "slow camera push-in",
    "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "duration_seconds": 8,
    "resolution": "1080p",
    "generate_audio": true
  },
  "callBackUrl": "https://your-app.example.com/hooks/spicy"
}

上の input は例です。受け付ける項目は、そのモデル自身の inputSchema だけで定まります。

標準フィールド

新しい全エンドポイントで、同じ概念に同じ snake_case の名前を使います。表はよくある項目で、全項目ではありません。完全な一覧はモデルの inputSchema です。

画像参照は、公開 HTTPS URL、アップロードを確定した spicy://、小さい data:image/…;base64,… URI です。動画・音声はインラインで送れません。メディア参照。

アダプターの重みの項目は、1 組の重みと適用する強さを示します。フィールド名は固定でも、項目の形は固定ではありません。URL か組み込みライブラリのキーかなど、重みの指定形式は各 items のサブスキーマで制限されるため、推測せず読みます。件数と必須の子項目も同様です。

標準項目にない実際の能力だけにモデル固有項目を設け、能力に合わせて命名します。古いエンドポイントはライブの inputSchema に以前の名前を残すことがありますが、新規ではコピーしません。

inputSchema と UI の注釈

全モデルの inputSchema は JSON Schema 2020-12 です。同じスキーマでサーバー検証、Playground のフォーム、例、見積もりを作ります。公式 TypeScript SDK は共通の要求と応答を静的に型付けしますが、各モデルの input は Record<string, unknown> のままです。モデル別の生成済み項目があると仮定せず、ライブスキーマで検証します。

このサイトにモデル別の静的パラメーター表はありません。唯一の情報源は GET /api/v1/models?includeSchema=1 の inputSchema で、Playground もこれを表示します。固定コピーは変更でずれ、そのずれを検出できません。自分の表の作り方はモデルカタログとスキーマを参照します。

取得するすべてのスキーマは次を満たします。

• ルートが object で、未知の項目を拒否する（additionalProperties: false）。
• required、型、列挙、範囲、長さ、配列上限、URI 形式、初期値、検証済み条件を示す。
• 各項目に空でない英語の description がある。
• 未検証の項目や初期値は推測せず除く。
• 条件は UI の表示だけでなく、ルートの anyOf / allOf（下記）で表す。
• 内部処理だけを変えるスイッチや、内容フィルターのスイッチを含まない。

表示用の注釈：x-ui

表示のメタデータは第 2 の検証スキーマではありません。各項目自身の x-ui 内に置き、キーは限定された snake_case です。

x-ui.widget は 13 種類の textarea、text、upload、multi-upload、select、radio、slider、number、switch、json、object-list、chat-messages、hidden のいずれかです。常にデータの形と一致します。select と radio は enum、slider は minimum と maximum の両方を持ち、exclusiveMinimum / exclusiveMaximum だけにはなりません。switch は boolean、multi-upload は items.type: string の配列、object-list は items.type: object と items.properties を持つ配列で、子項目ごとに type と description があります。chat-messages は配列、hidden は送信するが操作欄を出さない意味です。

配列自身の minItems / maxItems と items の制約は、ルートの required にないものも、サーバーで同じように適用します。object-list の items は、独自の required、additionalProperties: false、子の型、範囲、default を持つ完全なオブジェクトスキーマです。子項目にも初期値が適用され、省いた子は検証前に default で補います。必須でも初期値があれば実質的に省略可能です。初期値がない必須子の欠落、未知の子、範囲外の値は拒否します。

配列内の値の 400 は、要求全体でなく、項目名、0 始まりの位置、子項目を指します。修正する人へその位置を渡します。複数項目では、どれが範囲外か分かれば、切り分けでなく 1 行の修正で済みます。

未知の表示キーは無視します。x-ui キーの追加は後方互換の変更です。

{
  "type": "object",
  "required": ["prompt", "duration_seconds"],
  "additionalProperties": false,
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1,
      "description": "Describes the scene and its motion.",
      "x-ui": { "widget": "textarea", "order": 100, "primary": true, "rows": 4 }
    },
    "duration_seconds": {
      "type": "integer",
      "enum": [5, 8, 10],
      "description": "Output duration in seconds.",
      "x-ui": { "widget": "radio", "order": 90, "unit": "s", "affects_price": true }
    }
  },
  "x-pricing": { "variantFields": ["duration_seconds"], "billingMode": "variant_matrix" }
}

各 description は英語の文章で、そのまま項目のヘルプへ表示できます。

x-ui.affects_price: true は、変更時の再見積もりを UI へ伝えます。料金式ではなく、カタログの pricing や quantityField に代わりません。ルートの x-pricing は同じ事実をサーバー側から示し、variantFields は料金の段階を選ぶ項目で、必ず affects_price: true の部分集合です。billingMode は計量方式です。どちらも補助情報で、正式な額はカタログ、見積もり、タスクの値です。pricing の段階は料金の読み方にあります。

条件付きの項目

ルートに、ちょうど 2 形式で示します。

{
  "anyOf": [{ "required": ["image_url"] }, { "required": ["image_urls"] }],
  "allOf": [
    { "if": { "required": ["last_image_url"] }, "then": { "required": ["image_url"] } },
    { "if": { "properties": { "resolution": { "const": "4k" } } }, "then": { "required": ["seed"] } }
  ]
}

anyOf の枝は required だけで、「このうち少なくとも 1 つを渡す」です。allOf の各枝は 1 組の if → then です。if は required または properties.<field>.const で発動し、then は required だけを示します。「A を渡すなら B も必要」という意味です。

oneOf、not、dependentSchemas、dependentRequired はモデルの inputSchema に出ません。制約を表せてもフォームにできず、送信後に説明できない 400 として初めて分かるためです。上の 2 形式で、全条件付きエンドポイントに対応できます。

非同期のライフサイクル

queued -> running -> succeeded
                  -> failed
                  -> expired

createTask が Spicy のタスク ID を返します。recordInfo をポーリングするか、署名付きの Spicy Webhook を受けます。queued と running は非終端で、他が終端です。過去の canceled は互換性のため読み取れますが、新規タスクにキャンセル操作はありません。非同期タスクが状態の基準です。

モデル内の未知の非終端状態は、既知の終端かプラットフォームの絶対期限まで running へ対応させます。冪等でない送信で受理が不明な場合、二重生成・課金を防ぐため、闇雲に再送しません。

共通の応答とエラー

ネイティブ JSON API（/api/v1）は同じ外枠、/v1 と /v1beta は各プロトコルの形式を使います。

{
  "code": 200,
  "msg": "success",
  "data": {},
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

同期的な失敗では data がありません。変わり得る msg ではなく code で分岐し、サポートには request_id を使います。作成後の失敗は data.state: "failed" と安定した errorCode で示します。errorMessage は人向けで、モデルから具体的な理由があれば内部の名前、アドレス、アカウント情報を除いた英語の理由です。なければエラー言語のプラットフォーム文です。errorMessage でなく errorCode で分岐します。

結果とダウンロード

成功タスクの output.assets[] にファイルがあり、準備済みの各資産にはリンクがあります。

{
  "assets": [
    {
      "key": "tasks/2026/08/31/job_01k3m8x9q2z4v7n5p6r8s0t1w3/asset_01.mp4",
      "url": "https://example.r2.cloudflarestorage.com/results/asset_01.mp4?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
      "expiresAt": "2026-08-31T10:20:00Z",
      "mime": "video/mp4",
      "durationSeconds": 8,
      "bytes": 1234567
    }
  ]
}

url を API キーなしで直接ダウンロードします。通常 20 分有効で、最大 14 日の結果保持中はタスクを再取得して新リンクを得られます。保存途中なら pending: true で url はなく、保存が恒久的に失敗なら unavailable: true です。key は任意の download-url 用の識別子で、通常のダウンロードには不要です。リンクはすべて SpicyAPI の保存先を指します。

利用者への課金

カタログの pricing、startingPrice、quantityField、タスクの estimatedCost / cost は、利用者向け料金だけです。金額は 10 進数の USD 文字列です。内部の事業データは公開契約の外で、カタログ、タスク、Webhook、書き出したログに出ません。

互換性と廃止

新しい任意項目、無視できる応答項目、未知の x-ui は、動作を壊さず受け入れる変更です。

新しい必須項目、enum 値の削除、意味・型の変更、厳しい制限、公開モデル ID の変更は、新版か告知した廃止期間を伴います。公開 ID は不変です。移行には互換の別名か明示的な転送を使います。

カタログのキャッシュに従います。永久のスキーマを保存せず、ライブに呼べる項目がない場合、固定ページへ戻して判断しません。