hiapi API で seedance-2.0-fast を使用する方法：curl、Python、実行可能なリクエスト

本ガイドでは、seedance-2.0-fast を使って動画を生成するための最小リクエスト、このモデルが実際に受け付ける全入力フィールド、およびポーリングまたはコールバックで結果を待つ方法を説明します。以下の各リクエスト構造とエラーメッセージは実際の API で動作検証済みなので、コードをそのままコピーして使用できます。

構築するものと準備するもの

目標はただ一つ：テキストプロンプトを送信し、ダウンロード可能な MP4 URL を受け取ることです。seedance-2.0-fast は Seedance 2.0 の速度最適化版であり、最高解像度（上限 720p）を犠牲にして生成速度を高めているため、プレビュー、反復サイクル、大量の短尺動画クリップに最適です。

必要なものは 1 つだけ：hiapi API キーです。ダッシュボードから取得してください。形式は sk-... のようになります。すべての動画モデル（これを含む）は統一された非同期タスクエンドポイントで提供されます。まず POST /v1/tasks でタスクを作成し、その後タスク id で結果を取得します。動画に同期モードはありません。

現在の 1 クリップあたりの価格は料金ページを参照してください（このモデルは登場したばかりなので、ブログ記事の数字を鵜呑みにせず、そちらを優先してください）。

最小実行例（curl）

タスクを作成：

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "input": {
      "prompt": "A paper boat drifts down a rain-soaked street at dusk, cinematic, slow dolly-in",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

レスポンスのタスク id は data.taskId にあります：

{
  "data": {
    "taskId": "task_abc123..."
  }
}

状態が终态になるまでこのタスクをポーリングします：

curl "https://api.hiapi.ai/v1/tasks/task_abc123..." \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status が "success" のとき、動画 URL は data.output[0].url にあります。この URL は署名付きで有効期限があるため、ファイルを直ちにダウンロードし、ホットリンクしないでください：

curl -o clip.mp4 "<the output url>"

全入力フィールド（検証済み）

必須なのは prompt のみです。この表にないフィールドは 400 で拒否されます——このスキーマは追加プロパティを許可していません。

フィールド	型	必須	受け付ける値
prompt	string	はい	最小長 3 文字
duration	整数	いいえ	4–15（秒）
resolution	string	いいえ	480p、720p
aspect_ratio	string	いいえ	1:1、4:3、3:4、16:9、9:16、21:9、adaptive

特に説明すべき点が 2 つあります：

• duration は整数であり、文字列ではありません。"duration": "5" を送信すると検証に失敗し、duration: got string, want integer というエラーになります。
• 画像入力はありません。seedance-2.0-fast はテキストから動画への生成のみをサポートします。image_urls のようなフィールドはスキーマによって拒否されます。画像から動画への生成が必要な場合は、画像から動画への API ワークフローガイドでその機能をサポートするモデルを確認してください。

Python での同じフロー

SDK は不要です——requests で十分です：

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, duration: int = 5,
                resolution: str = "720p", aspect_ratio: str = "16:9") -> str:
    payload = {
        "model": "seedance-2.0-fast",
        "input": {
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    r = requests.post(API_BASE, json=payload, headers=HEADERS, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task(
    "A barista pours latte art in a sunlit cafe, shallow depth of field"
)
task = wait_task(task_id)
video_url = task["output"][0]["url"]

# The URL is signed and expires — persist the bytes immediately.
with open("clip.mp4", "wb") as f:
    f.write(requests.get(video_url, timeout=120).content)
print("saved clip.mp4")

success / fail 以外の状態はすべて「まだ実行中」として扱ってください——そうすれば、将来中間状態の名前が変わってもループは堅牢なままです。

本番環境での注意点

ポーリングの代わりにコールバックを使う

スクリプト以外のあらゆる場面では、タスク作成時にコールバックを登録してポーリングを完全に省略できます：

{
  "model": "seedance-2.0-fast",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

"when": "final" を使うと、タスクが终态に達したときにあなたのエンドポイントへ POST がちょうど 1 回届きます。ポーリングは CLI や notebook に適していますが、大規模に実行する場合はコールバックの方が優れています（無駄なリクエストも、ポーリング間隔による遅延もありません）。フックが発火しないようであれば、コールバックのトラブルシューティングガイドを参照してください——ほとんどは URL の到達性の問題か、ハンドラーが 2xx 以外のレスポンスを返していることが原因です。

冪等性

タスクの作成は無料ではないため、あなた側で重複送信を防いでください：各ビジネスイベントが最大 1 回の POST /v1/tasks 呼び出しに対応するようにします（例えば、リトライ前に taskId を注文/タスクの行と関連付けて保存する）。タスク作成後にプロセスがクラッシュした場合は、保存済みの taskId を読み直し、GET /v1/tasks/<id> を再開することで復旧できます——ポーリングの有無にかかわらず、タスクはサーバー側で実行を続けます。

実際に遭遇するエラー

症状	意味	修正
400 かつ error_code: "INVALID_REQUEST"	入力がスキーマ検証に失敗；message が具体的なフィールドを示す（例：duration: maximum: got 20, want 15）	そのフィールドを修正；上の表の 4 つのフィールドのみ許可される
401 かつ error.code: "permission_denied"	キーが無効、または有効だがこのモデルが有効化されていない	ダッシュボードでキーを確認；モデル権限はキーごとに設定される
GET 時に 404 かつ "task not found"	タスク id が誤っているか、そのアカウントに属していない	作成時に返された taskId を、同じアカウントで使用する
タスク状態が "fail" で error オブジェクトを伴う	生成自体が失敗	error.code/error.message を読み、プロンプトを調整してリトライ

2 種類のエラーラッピングに注意してください：検証エラーは message をトップレベルに置き、認証エラーは error の下にネストします。汎用ミドルウェアを書く場合は、両方に対応する必要があります。

seedance-2.0-fast の適用場面

1080p または 4K の出力が必要な場合は、完全版の seedance-2.0 を使用してください——同じエンドポイント、同じフロー、より高い解像度上限（さらに明示的な aspect_ratio の指定が必要です）。Seedance シリーズとプラットフォーム上の他の動画モデルとの比較をより包括的に知りたい場合は、動画モデル比較を参照してください。各モデルの完全なパラメータリファレンスはドキュメントにあり、モデルページでは現在の機能と料金状態を追跡しています。

よくある質問

seedance-2.0-fast はどの解像度をサポートしていますか？ 480p と 720p です。これが速度の代償です——完全版の seedance-2.0 は同じ /v1/tasks フローで最大 1080p と 4k まで対応します。

seedance-2.0-fast で画像から動画を生成できますか？ いいえ。入力スキーマは prompt、duration、resolution、aspect_ratio のみを受け付け、画像フィールドは検証エラーで拒否されます。hiapi での画像から動画への生成オプションについては、画像から動画へのワークフローガイドを参照してください。

生成される動画の長さはどれくらいですか？ duration は 4 から 15 秒の整数を受け付けます。この範囲外の値はタスク作成前に検証で失敗します（拒否されたリクエストは課金されません）。

ポーリングとコールバックのどちらを使うべきですか？ スクリプトや低並行数の場合は、約 5 秒ごとのポーリングで十分です。本番規模では、作成時に callback: {"url": ..., "when": "final"} を渡し、hiapi が终态をあなたにプッシュするようにしてください——数十回ではなく 1 回のリクエストで済みます。

他のモデルでは有効なキーが、ここでは 401 permission_denied になるのはなぜですか？ モデルへのアクセス権限はキーごとにスコープ設定されます。このモデルで 401 かつ permission_denied が返る場合、キーは存在するものの seedance-2.0-fast に対して有効化されていないことを意味します——ダッシュボードでそのキーのモデル権限を確認してください。

出力 URL の有効期限はどれくらいですか？ 署名付き URL であり、期限切れになります。タスク成功後すぐに MP4 をダウンロードして自分で保存してください。元の出力 URL を長期間存在する場所に埋め込まないでください。