動画生成

非同期ジョブで動画を作る /v1/videos の使い方です。

対応モデル

動画生成は /v1/videos です。テキスト生成とは別サーフェスのため、これらのモデル ID は GET /v1/models には含まれません（GET /v1/videos/models で対応モデルと単価を確認できます）。トライアルキーは対象外です（本番モデル + 有料キー）。

モデル ID	モデル名	仕様
`minimax-h3`	MiniMax H3自社DC	解像度 2K / 長さ 5〜15 秒 / 音声あり（既定 ON）アスペクト比 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 参照画像最大 2 枚

生成の流れ

生成は分単位の非同期ジョブです。POST /v1/videos が 202 でジョブ ID を返し、GET /v1/videos/{id} で完了を確認してから GET /v1/videos/{id}/content で mp4 を取得します。OpenAI Video API 互換の形なので、OpenAI SDK の videos.create / videos.retrieve / videos.download_content がそのまま使えます。

curl https://hai-api.hcloud.ltd/v1/videos \
  -H "Authorization: Bearer hai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A product spin on a clean white table, soft studio light",
    "seconds": 5,
    "aspect_ratio": "16:9"
  }'

# 完了確認（status が completed になるまで繰り返す）
curl https://hai-api.hcloud.ltd/v1/videos/<id> \
  -H "Authorization: Bearer hai_..."

# mp4 の取得
curl -L https://hai-api.hcloud.ltd/v1/videos/<id>/content \
  -H "Authorization: Bearer hai_..." \
  -o out.mp4

import time
from openai import OpenAI

client = OpenAI(
    base_url="https://hai-api.hcloud.ltd/v1",
    api_key="hai_...",
)

video = client.videos.create(
    model="minimax-h3",
    prompt="A product spin on a clean white table",
    seconds="5",
)
while video.status in ("pending", "in_progress"):
    time.sleep(10)
    video = client.videos.retrieve(video.id)

client.videos.download_content(video.id).write_to_file("out.mp4")

パラメータ

パラメータ	内容
`prompt`	生成内容のテキスト（必須）
`seconds`	尺（整数秒。文字列も可）。省略時は最短尺。`duration` も同義で受け付けます
`aspect_ratio`	上の表のアスペクト比から選びます（省略時 `16:9`）
`input_reference`	参照画像 1 枚。`https` URL または画像ファイル
`input_references`	参照画像の配列（`[{ "type": "image", "url": "https://…" }]`）。`https` URL のみ
`frame_images`	開始・終了フレームの指定（`{ "type": "first_frame" \| "last_frame", "image_url": "…" }`）
`generate_audio`	音声を同時に生成するか（既定 true）。`false` でも音声トラック自体は含まれます

仕様と課金

参照画像の枚数は frame_images / input_reference / input_references の合計で数えます。上の表の上限を超えると 400 です。
seed は非対応です（指定すると 400）。解像度は 2K 固定で、size は受け付けません。
課金は秒単価と参照画像の枚数で決まります（トークン課金ではないため、利用履歴の入力 / 出力トークンは 0 です）。単価は料金をご覧ください。
投入時に見積り全額をクレジットから予約します。残高不足の場合は 402 で送信しません。完了時に実額で精算し、失敗・期限切れのジョブは課金せず予約を全額解放します。
/content は完了前に呼ぶと 409 です。レスポンスは Content-Type: video/mp4 固定で、保持期限は GET /v1/videos/{id} の expires_at（UNIX 秒）で確認できます。期限が切れる前に取得・保存してください。
mp4 には「AI で生成した動画である」ことを示すメタデータ（comment フィールドに {"generated_by":"HAI","ai_generated":true}）が入ります。映像に焼き付く透かしやロゴはありません。
音声トラックは generate_audio の指定にかかわらず含まれます（無音の場合があります）。不要な場合は取得後に取り除いてください。