チュートリアル：画像から動画を作る

アカウント、残高、API キーを用意する

まずアカウントの準備の手順を済ませてください。終わった時点で、次のものがそろっているはずです。

• 残高にお金が入っている SpicyAPI アカウント
• sk-spicy- で始まる API キー
• そのキーを SPICY_API_KEY という名前の環境変数に保存した状態。環境変数とは、ターミナルが自分の実行するプログラムに渡す、名前の付いた値のことです。これを使えば、キーをコマンドやコードに書かずに済みます。

いま使っているターミナルウィンドウでキーが設定されているかを、キー全体は表示せずに確認します。

echo "${SPICY_API_KEY:0:9}"

期待される結果： sk-spicy- と表示されます。何も表示されない場合やエラーになる場合は、このウィンドウではキーが設定されていません。アカウントの準備に戻ってください。

画像を作業フォルダーに置く

このチュートリアル用のフォルダーを作り、そのフォルダーでターミナルを開きます。このページのコマンドはすべてこのフォルダーで実行し、コマンドが作るファイルもすべてここに保存されます。

mkdir -p ~/spicy-video
cd ~/spicy-video

画像をそのフォルダーにコピーし、start-frame.jpg という名前にします（PNG の場合は start-frame.png にして、このページで start-frame.jpg と書かれている箇所はすべてその名前に読み替えてください）。

最初のフレームに向いている画像の条件は次のとおりです。

• 形式とサイズ： JPEG、PNG、WebP、GIF のいずれかで、10 MiB（約 10 メガバイト）までです。モデルによっては独自により厳しい制限があり、それはステップ 1 で確認できます。
• ファイルが実際にその形式であること。 SpicyAPI は、ファイル名だけでなくファイルの中身を確認します。スマートフォンの写真は HEIC 形式であることが多く、名前を .jpg に変えても変換はされません。いったん画像を開き、JPEG として書き出すか保存し直してください。
• 縦横の形： 画像は動画の最初のフレームになります。横長の動画には横長の画像を、縦長の動画には縦長の画像を使ってください。aspect_ratio という設定を用意しているモデルもあります。
• 権利： 使用が認められている画像を使ってください。

選んだツールを準備する

npm install -g @spicyapi/cli
spicyapi --version

spicyapi balance

1. モデルを選び、その設定を確認する

やること： あなたのアカウントで使える、画像から動画を作るモデルを一覧表示して 1 つ選び、そのモデルが受け付ける設定を確認します。

spicyapi models list --modality video --task image-to-video --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

一覧で見るポイント：

設定の読み方。 inputSchema は、そのモデルの設定の一覧を JSON Schema で書いたものです。

• required には、必ず送る必要がある設定が並びます。この種類のモデルでは image_url が必ず含まれ、ほとんどのモデルでは prompt も必須です。
• properties には、そのモデルが受け付けるすべての設定が並びます。それぞれに type と、平易な英語で書かれた description があり、多くの場合は enum（許される値の一覧）、minimum と maximum、default（その設定を省略したときに使われる値）も付いています。
• 各設定の中にある x-ui には、表示用のヒントが入っています。x-ui.affects_price: true は、その設定を変えると価格が変わることを意味します。
• 「A を送る場合は B も送る必要がある」といった条件を最上位に追加しているモデルもあります。その読み方は Spicy Schema で説明しています。
• examples には、サーバーが検証済みの完全な入力例が入っています。安心して出発点にできます。

よく使う設定。 名前はすべてのモデルで共通ですが、各モデルが受け付けるのはその一部だけで、使える値もモデルごとに異なります。

ここで起きたこと： あなたのアカウント向けのライブカタログを、あなたの価格も含めて読みました。何も課金されていません。カタログの読み取りはアカウントのリクエスト数の上限にカウントされるため、動画を作るたびに繰り返す必要はありません。モデルを変えたときや 400 が返ってきたときに、もう一度確認してください。

2. 画像をアップロードする

やること： start-frame.jpg をアップロードし、返ってきた spicy:// アドレスをコピーします。アップロードは無料です。

spicyapi files upload start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z

ここで起きたこと： 画像があなたのアカウント用に非公開で保存され、検証され（実際の形式が申告した種類と一致している必要があります）、spicy:// アドレスが付けられました。このアドレスは Web のリンクではありません。使えるのはあなたのアカウントだけで、しかもタスクの入力の中でしか使えません。使える期間は 1 日です（expiresAt を参照）。それを過ぎたら、画像をもう一度アップロードしてください。

アップロードに失敗した場合：

3. 動画の内容を書き、価格を確認する

やること： 設定を input.json というファイルに書き、見積もりを取ります。

input.json を書く。 まずは、画像から動画へのモデルならどれでも受け付ける 2 つの設定から始めます。prompt には自分の文を書き、image_url の値は、ステップ 2 でコピーした uri に置き換えてください。

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

省略した設定には、そのモデルの default が使われます。自分で指定したい場合は、そのモデルの properties に載っている設定だけを、許されている値で追加します。たとえば、モデルに duration_seconds と resolution があり、次の値が使える場合は、このようになります。

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

作業フォルダーにファイルを保存します。

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

引用符は、曲がった引用符ではなく、まっすぐな普通の引用符（"）を使ってください。また、最後の設定のあとにはカンマを付けないでください。

見積もりを取る：

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: …
maxCharge: …
currency: USD
quantity: 5
unit: per_second
expiresAt: 2026-09-17T08:05:00Z

ここで起きたこと： SpicyAPI が入力をモデルの設定と照らし合わせ、このリクエストそのものの価格を計算しました。何も開始されておらず、何も課金されていません。 estimatedCost はいま開始した場合に仮押さえされる金額で、maxCharge はかかりうる最大の金額です。quantity と unit は、何に対して支払うのか（たとえば 5 秒分）を示します。

見積もりの有効期間は 5 分で、まったく同じ入力に対してだけ有効です。長さや解像度を変えたら、もう一度見積もりを取って価格を比べてください。見積もりではタスクを開始するときと同じ確認が行われるので、問題があればここで無料で見つかります。400 は入力がモデルの設定に合っていないことを意味し（ステップ 1 を見ながら input.json を直してください）、40201 は残高が足りないことを意味します。それ以外のコードはステップ 7 にまとめています。

4. 生成を開始する

冪等キーをわかりやすく言うと。 注文番号のように、1 本の動画に付けるラベルです。接続が切れて、動画の生成が始まったかどうかわからなくなったら、同じリクエストを同じラベルでもう一度送ってください。SpicyAPI は 2 本目を開始して課金するのではなく、すでに開始したタスクを返します。ラベルは、同じ API キーで 24 時間有効です。別の動画には新しいラベルを使ってください。同じラベルで別の入力を送ると、409 で拒否されます。詳しくは冪等性を参照してください。

やること：

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json

Estimated charge: USD …; maximum charge: USD …. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? … Continue? [y/N]

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

ここで起きたこと： SpicyAPI が生成を受理し（ここからはタスクと呼びます）、estimatedCost を残高から仮押さえしました。この金額は、この動画にかかりうる最大額でもあります。state: queued は、順番を待っていることを意味します。deadlineAt は完了の期限で、それまでに終わらなければ expired で終了し、何も課金されません。deadlineAt は、ファイルの保存期限ではありません。

見積もりを添えて送ることは、「表示された価格でなければ受け付けないでほしい」という意味になります。その間に価格や入力が変わっていれば、別の金額が仮押さえされるのではなく、リクエストが 40901 で拒否されます。CLI はこれを自動で行います。

接続が切れてタスク ID が表示されなかった場合は、 新しいラベルでやり直すことはしないでください。2 本目の動画が作られ、その分も課金されてしまいます。代わりに、同じラベルでリクエストを繰り返します。

• CLI：spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied>（<the value you copied> はコピーしておいた値に置き換えます）。待機が中断されたタスクを再開するを参照してください。
• SDK：node generate.mjs --yes をもう一度実行します。idempotency-key.txt が再利用されます。
• HTTP：「動画の生成を開始する」のブロックをもう一度実行します。idempotency-key.txt が再利用されます。

ステップ 4 が拒否された場合は、何も作成されておらず、何も課金されていません。理由と対処法はステップ 7 にあります。

5. 動画の完成を待つ

やること： タスクが終わるまで状態を確認します。動画はふつう数分かかります。

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000 --json

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

ここで起きたこと： 使っているツールが、数秒ごとに SpicyAPI にタスクの状態を問い合わせました。状態は queued（待機中）、running（生成中）と進み、最後に succeeded、failed、expired のいずれか 1 つの最終状態になります。成功したあと、ファイルは SpicyAPI 自身のストレージにコピーされます。これにはさらに数秒かかり、それまでは結果に pending: true が表示されます。settled が true になれば、cost は確定しています。

• ターミナルを閉じても、Ctrl + C を押しても、タスクはキャンセルされません。 止まるのは待機だけです。タスク ID を控えておき、あとでこのステップをもう一度実行してください。
• 数秒に 1 回より頻繁には確認しないでください。 タスクの確認は、開始とは独立した、アカウントの読み取り枠を使います。レート制限を参照してください。
• アプリやサーバーの場合は、 こちらから問い合わせるのではなく、タスクが終わったときに SpicyAPI から知らせてもらいましょう。待たずに通知を受け取るを参照してください。

6. 動画をダウンロードして保存する

やること： 新しいダウンロードリンクを取得し、ファイルをパソコンに保存します。

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

ここで起きたこと： どの結果にも、直接ダウンロードできるリンクが付いています。リンクは約 20 分有効で、API キーは要りません。リンクにキーを付け加えることは絶対にしないでください。期限が切れたら、タスクをもう一度照会する（または files download-url を使う）と、新しいリンクが得られます。

7. うまくいかないとき

問題には 2 種類あり、それぞれ対処の仕方が異なります。

リクエストが拒否される。 コマンドや呼び出しに、すぐにエラーが返ります。何も作成されておらず、何も課金されていません。 メッセージに理由が書かれており、エラーには code と、サポートに問い合わせるときに伝えるリクエスト ID（req_…）が付いています。

タスクが失敗する。 タスクは受理されたものの、succeeded ではなく failed か expired で終わります。タスクには理由を示す errorCode と、詳しい内容を文章で伝える errorMessage が付いています。 失敗・期限切れのタスクでは通常、仮押さえ額が全額解放されます。ただし、モデルページに明記された一部のコンテンツ拒否は、受理時の見積額で課金されます。最終請求額は settled と cost で確認してください。

確認するには、次のようにします。

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

そのうえで、メッセージの文面ではなく errorCode に基づいて、どうするかを決めます。

これ以外の値は、upstream_failed と同じように扱ってください。すべての一覧はエラーにあります。

失敗したタスクをもう一度実行する。 再試行すると、同じモデルと同じ入力で、モデルの現在の価格による新しいタスクが作られます。ステップ 4 と同じくお金がかかります。また、元の入力がそのまま使われるので、その入力で使ったアップロードの期限がすでに切れている場合は、再試行ではなく、もう一度アップロードして新しいタスクを開始してください。

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait --wait-timeout-ms 1800000

再試行できるのは、failed と expired のタスクだけです。成功した動画の別バージョンを作りたい場合は、新しいラベルを用意してステップ 3 に戻ってください。受理されたタスクをキャンセルする方法はありません。詳しくはタスク確定と再試行を参照してください。