動画生成タスクの作成

非同期の動画タスクを作成します。受付後に返されるタスク ID を使って状態を確認し、動画 URL を取得します。

エンドポイント

POSThttps://fablun.com/api/v3/contents/generations/tasks

リクエストヘッダー

パラメータ	必須	説明
`Authorization`	はい	`Bearer YOUR_API_KEY`
`Content-Type`	はい	`application/json`
`Idempotency-Key`	いいえ	指定を推奨します。1～128 文字で、英数字と _.:- のみ使用できます。同じリクエストの再試行では元の値を使用します。

リクエストパラメータ

パラメータ	型	必須	既定値	説明
`model`	string	はい	—	h3-pro または h3-standard。アカウントでモデルの利用権限が必要です。
`content`	object[]	はい	—	1～8 項目で、text が最低 1 項目必要です。image_url で開始フレームを 1 枚追加できます。結合後のプロンプトは最大 2000 文字です。
`resolution`	string	いいえ	480p	480p / 720p。モデルの対応仕様を確認し、明示的に指定してください。
`duration`	integer	いいえ	5	単位は秒です。H3 Pro の 480p テキスト動画・画像動画は 5・10・12 秒、720p は 5 秒に対応します。他のモデルは「モデルと仕様」を確認してください。
`seed`	integer	いいえ	-1	省略または -1 でランダムになります。0～2147483647 を指定でき、0 も有効です。取得時には実際のシード値が返されます。
`ratio`	string	いいえ	16:9	H3 Pro の 480p・720p は 1:1、3:4、4:3、16:9、9:16 を受け付けます。実際の供給は検証済みノードに依存します。
`generate_audio`	boolean	いいえ	true	true は音声を保持し、false は映像を再エンコードせずに消音します。
`watermark`	boolean	いいえ	false	現在は false 固定です。
`service_tier`	string	いいえ	default	default のみ対応しています。flex は利用できません。
`execution_expires_after`	integer	いいえ	172800	待ち時間を含むタスクの有効期間。単位は秒、3600～259200 で、プラットフォーム上限が適用されます。
`priority`	integer	いいえ	0	0～9。アカウント間の公平性と待機タスクの保護を維持したうえで適用されます。実行中の推論は中断しません。
`callback_url`	string	いいえ	—	公開 HTTPS コールバック URL。省略して直接ポーリングすることもできます。
`safety_identifier`	string	いいえ	—	最大 64 文字のエンドユーザー識別子。

return_last_frame、camera_fixed、draft に指定できるのは次の値のみです： false。未対応の機能や不明なフィールドは 422 を返します。

content オブジェクト

型	フィールド	説明
text	`text`	必須のプロンプトです。複数のテキストは改行で結合されます。
image_url	`image_url.url`	公開画像 URL または完全な Base64 data URL。
image_url	`role`	対応する値は次のみです： `first_frame`。省略時も開始フレームとして扱います。

JSON · テキストと開始フレーム

{
  "content": [
    {
      "type": "text",
      "text": "カメラがゆっくり近づき、人物が自然にほほえむ。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/first-frame.jpg"
      },
      "role": "first_frame"
    }
  ]
}

リクエスト例

モデルモード解像度動画の長さアスペクト比Seed

Python · 作成と自動ポーリング

import os, time, uuid
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ["ARK_API_KEY"],
    base_url="https://fablun.com/api/v3",
)

request_key = str(uuid.uuid4())  # 新しいタスクでのみ生成し、通信の再試行では保存済みの値を再利用します。
print("Idempotency-Key:", request_key)
task = client.content_generation.tasks.create(
    model="h3-pro",
    content=[
        {"type":"text","text":"夜明けに白いデイジーに蝶がとまる。マクロ撮影、柔らかな自然光。"}
    ],
    resolution="480p", duration=5, ratio="16:9",
    
    extra_headers={"Idempotency-Key": request_key},
)
print("task_id:", task.id)  # ID を保存し、通信が中断した場合は同じタスクの確認を再開します。

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = client.content_generation.tasks.get(task_id=task.id)
    if result.status == "succeeded":
        print(result.content.video_url)
        break
    if result.status in ("failed", "expired", "cancelled"):
        raise RuntimeError(result.error or result.status)
    time.sleep(2)
else:
    raise TimeoutError(f"待機時間を超えました。同じタスクを引き続き確認してください：{task.id}")

レスポンスフィールド

HTTP 200 · application/json

{
  "id": "cgt-0123456789abcdef0123456789abcdef"
}

フィールド	型	説明
`id`	string	タスク ID。取得、キャンセル、調査のために保存してください。

HTTP 200 は受付成功を表し、生成完了ではありません。動画 URL は取得レスポンスの次の項目に返されます： content.video_url 。

開始・終了フレーム

H3 Pro の 5 秒動画で開始・終了フレームに対応。480p / 720p、1:1・3:4・4:3・16:9・9:16 が利用できます。各 role は 1 枚、last_frame には first_frame が必要です。動画 1 件として課金し、キャンセル・審査・コールバックは通常のタスクと同じです。出力用 return_last_frame は未対応です。

{
  "model": "h3-pro",
  "content": [
    {
      "type": "text",
      "text": "A red ball rolls from left to right."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/first-frame.jpg"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/last-frame.jpg"
      },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9",
  "generate_audio": true
}

動画圧縮（任意）

compress: boolean、既定値 false。true で北京の CPU 配信処理にて圧縮します。解像度、フレームレート、音声は維持します。追加生成料金はありません。5% 未満の削減またはエンコード失敗時は元動画を返し、compression.applied / reason で確認できます。通常の審査、有効期限、署名付きコールバックが適用されます。

{
  "model": "h3-pro",
  "content": [
    {
      "type": "text",
      "text": "A cat walks through a garden."
    }
  ],
  "resolution": "720p",
  "compress": true
}