チュートリアル

Creatify Boreal API の使い方：テキスト・画像・音声から動画を生成する

Oct 23, 2026

creatify-boreal は hiapi 上の動画モデルで、音声とサウンドがすでにミックスされた完成済みのクリップを返します。1 つのモデル id で 3 つの出発点をカバーします：プロンプトのみ、プロンプト＋参照画像、またはプロンプト＋独自のナレーション音声です。本ガイドではリクエスト、ポーリングループ、そして実際に一度リアルな生成を実行した結果を紹介します。

API キーは hiapi ダッシュボードから取得してください。すべての呼び出しは統一タスクエンドポイント POST /v1/tasks を通じて行います。

入力フィールド

これらのフィールドは実際のモデルページと照合し、さらに /v1/tasks に意図的に無効な値を送信して検証しました。無効な値は 400 を返し、課金されません。

フィールド	必須	受け付ける値
`prompt`	はい	テキスト、最大 5000 文字
`image_url`	いいえ	JPG/PNG/WebP、10 MB；被写体と構図を設定
`audio_url`	いいえ	MP3/WAV/M4A、15 MB；先頭の `duration` 秒のみ使用
`negative_prompt`	いいえ	最大 2000 文字
`resolution`	いいえ	`720p`、`1080p`、`2k`
`aspect_ratio`	いいえ	`auto`、`16:9`、`9:16`、`1:1`、`4:3`、`3:4`
`duration`	いいえ	整数秒、1 から 20

これら 3 つのモードは独立したモデル id ではありません。テキストから動画を生成する場合は image_url と audio_url を省略します。画像から動画を生成する場合は image_url を追加します。audio_url を追加すると（通常は画像も同時に提供）、出演者があなたのナレーションに合わせて動きます。

最小限の動作するリクエスト

curl -X POST 'https://api.hiapi.ai/v1/tasks' \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "creatify-boreal",
    "input": {
      "prompt": "縦型自撮りスタイルの UGC 動画：若い女性が明るい寝室で柔らかなピンクのリップスティックを掲げ、カメラに向かって「これ、私の冬を乗り切った唯一のリップなんだよね」と言う。自然な部屋の環境音。",
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "duration": 4
    }
  }'

レスポンスでタスク id が返ります：

{"code":200,"data":{"taskId":"tk-hiapi-01M5MJC8NG8E1E0XN9NEJRDBQH"},"message":"success"}

Python：送信とポーリング

import os, time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def create(payload: dict) -> str:
    r = requests.post(BASE, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id: str, every: int = 10, limit: int = 900) -> dict:
    start = time.time()
    while time.time() - start < limit:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except (requests.RequestException, ValueError):
            time.sleep(every)  # 一時的なネットワークエラー：同じ id でポーリングを続行
            continue
        if d["status"] == "success":
            return d
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

task_id = create({
    "model": "creatify-boreal",
    "input": {
        "prompt": "縦型自撮りスタイルの UGC 動画：若い女性が柔らかなピンクのリップスティックを掲げ、カメラに向かって「これ、私の冬を乗り切った唯一のリップなんだよね」と言う。自然な部屋の環境音。",
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 4,
    },
})
result = wait(task_id)
print(result["output"][0]["url"])

ステータスは handling、archiving を経て success に至ります。動画 URL は data.output[0].url にあります。

画像モードと音声モード

画像から動画を生成する場合はフィールドを 1 つ追加するだけです：

{"model": "creatify-boreal",
 "input": {"prompt": "この女性がキッチンでカメラに向かって微笑みながら話す：「コーヒーをこのオーツミルクのラテブレンドに替えたんだよね。」自然なキッチンの環境音。",
           "image_url": "https://your-cdn.example/presenter.jpg",
           "resolution": "720p", "duration": 8}}

音声駆動モードではナレーションファイルを指す audio_url を追加します。モデルページでは、ナレーションが動画内に保持され、唇がナレーションの動きに追従すること、そして音声の先頭 duration 秒のみが使用されることが説明されているため、duration は求めるクリップの長さに設定してください。モデルページの音声サンプルは音声と参照画像を組み合わせていますが、私自身は画像＋音声の生成を実行していないため、この組み合わせは本記事ではドキュメント記載であり検証済みではありません。

実際の実行の様子

上記のリクエスト（テキストのみ、720p、9:16、4 秒）を実行しました。

生成時間： タスクは handling 状態に約 283 秒、その後 archiving 状態に約 10 秒かかりました。4 秒のクリップであっても、秒ではなく分単位で計画してください。短いタイムアウトではなく、10 秒ごとのポーリングまたはコールバックを使用してください。
出力ファイル： 720x1280 の MP4、H.264 動画 24 fps に AAC 音声トラック、長さ 4.04 秒。リクエストに音声フィールドがないにもかかわらず音声が存在しますが、これはモデルのネイティブなサウンドデザインに沿ったものです。
一時 URL： 出力 URL は temp.hiapi.ai にあり、約 7 日後に期限切れになる expireAt が付いています。ページからリンクするのではなく、ファイルをダウンロードして自分で保存してください。
コストの形： 秒単位で課金され、resolution にも依存します（料金ページを参照）。そのためプロンプトの反復を最も安く行うには 720p かつ短めの duration を使い、その後最終版を 1080p や 2k で再レンダリングしてください。

私が遭遇した落とし穴

誤った値は即座に失敗し、無料です。 aspect_ratio: "7:5"、duration: 25、resolution: "4k" を送信すると、いずれも HTTP 400 INVALID_REQUEST を返し、メッセージに許可される値（'auto', '16:9', '9:16', '1:1', '4:3', '3:4'、最大 20、および '720p', '1080p', '2k'）が列挙されます。これを利用して、送信前に自分のフォームを検証してください。
誤ったメディア URL は後でポーリング時に失敗します。 audio_url: "https://example.com/a.mp3"（実際の音声ファイルではない）を送信しました。作成呼び出しは HTTP 200 とタスク id を返しましたが、約 15 秒後にタスクは status: "fail" と error.code: "INVALID_REQUEST" で終了しました。つまり作成時に 200 が返っても、メディアが利用可能であることを意味しません。常に最終ステータスを確認し、data.error を読んでください。この場合、失敗は HTTP エラーとしてではなく、HTTP 200 のポーリングレスポンス内で示されました。
失敗は HTTP ステータスではなく status: "fail" です。 ポーリングリクエスト自体は 200 を返すため、data.status を確認してください。