公式 SDK クイックスタート

公式 SDK は一連の流れ（作成 → ポーリング → ダウンロード）をまとめ、冪等キーの自動生成と型付きエラーを提供します。Node SDK は依存パッケージがなく、Python SDK は httpx のみに依存します。現在は GitHub リポジトリで提供しており、npm / PyPI での公開は別途お知らせします。

Node

npm install github:openaiav/sdk-node   # npm release to be announced

import { OpenAiav } from '@openaiav/sdk'
const client = new OpenAiav({ apiKey: process.env.OPENAIAV_API_KEY })
const task = await client.generations.createAndWait({
  model: 'seedance-2.5-oa', prompt: 'She walks into the sunlight.',
  resolution: '480p', aspectRatio: 'adaptive', durationSeconds: 4,
  generateAudio: false
})
await client.generations.downloadToFile(task.id, './out.mp4')

Python

pip install git+https://github.com/openaiav/sdk-python   # PyPI release to be announced

from openaiav import OpenAiav
client = OpenAiav(os.environ["OPENAIAV_API_KEY"])
task = client.generations.create_and_wait({
    "model": "seedance-2.5-oa", "prompt": "She walks into the sunlight.",
    "resolution": "480p", "aspectRatio": "adaptive", "durationSeconds": 4,
    "generateAudio": False,
})
client.generations.download_to_file(task["id"], "./out.mp4")

4 ステップで統合

1. サーバー側の環境変数 OPENAIAV_API_KEY を使って https://api.openaiav.com/v1/models を呼び出し、現在のモデルキー、料金、reference_modes を取得します。
2. POST /v1/generations に prompt、referenceMode、referenceImages を送信します。参照画像は公開 HTTPS URL で、事前登録は不要です。作成成功は HTTP 201 です。
3. 返された id を保存し、poll_after_ms の後に同じ GET /v1/generations/{id} をポーリングします。processing、result_pending、submission_unknown はいずれも待機を続け、作成をやり直さないでください。
4. 状態が succeeded になったら GET /v1/generations/{id}/content でダウンロードします。全体取得は HTTP 200、単一のバイト範囲は 206 です。

認証と冪等性

export OPENAIAV_API_KEY='oav_...'
# One Idempotency-Key per create intent: every run of this script makes a new one.
# Reuse it only when retrying this same create. No uuidgen? IDEMPOTENCY_KEY=$(python3 -c 'import uuid;print(uuid.uuid4())')
IDEMPOTENCY_KEY=$(uuidgen | tr 'A-Z' 'a-z')
echo "Idempotency-Key: $IDEMPOTENCY_KEY  (reuse this value only when retrying this same create)"

すべてのリクエストで Authorization: Bearer oav_... を送信し、キーはサーバー側に保管してください。作成には generation:create、ポーリングとダウンロードには generation:read が必要です。作成の意図ごとに新しい Idempotency-Key（UUID）を生成するため、サンプルは実行のたびに新しいキーを使います。再利用するのは、ネットワークの結果が不明で同じ作成を再試行する場合だけです。同じキーを異なるボディで使わないでください。

リクエストヘッダー

エンドポイント一覧

ステップ 1：モデルの対応状況を取得

モデルの対応状況をハードコードしないでください。reference_modes に記載されたモードのみを送信し、非対応の組み合わせは送信前に非表示または無効化してください。最小構成のサンプルは seedance-2.5-oa で 4 秒・480p・音声なしのリクエストを示しています。

curl --fail-with-body 'https://api.openaiav.com/v1/models' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY"

最小構成の公開動画サンプル

サンプルには一連の流れがすべて含まれます：作成 → 同じタスクをポーリング → ダウンロード。 first_frame は参照画像 1 枚と adaptive を使用し、generateAudio=false で音声を要求しません。成功時のコードは 201、200、200/206 です。失敗時はまず HTTP を確認し、次に error.code をご確認ください。

# Keep OPENAIAV_API_KEY in an environment variable; do not paste secrets into shell history.
# One Idempotency-Key per create intent: every run of this script makes a new one.
# Reuse it only when retrying this same create. No uuidgen? IDEMPOTENCY_KEY=$(python3 -c 'import uuid;print(uuid.uuid4())')
IDEMPOTENCY_KEY=$(uuidgen | tr 'A-Z' 'a-z')
echo "Idempotency-Key: $IDEMPOTENCY_KEY  (reuse this value only when retrying this same create)"

# 1. Create — success: HTTP 201. On failure, the response body contains error.code.
# Lost response (timeout or dropped connection)? Re-run this same command in this shell:
# the unchanged $IDEMPOTENCY_KEY returns the original task instead of creating a second one.
curl --fail-with-body --request POST 'https://api.openaiav.com/v1/generations' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5-oa",
  "prompt": "A young woman finishes a letter and walks from a stone cottage into the morning sunlight",
  "resolution": "480p",
  "aspectRatio": "adaptive",
  "durationSeconds": 4,
  "referenceMode": "first_frame",
  "referenceImages": [
    "https://developers.openaiav.com/samples/seedance-letter-reference.webp"
  ],
  "generateAudio": false,
  "outputFormat": "mp4"
}'

# 2. Save the returned id as TASK_ID. Poll the same id — success: HTTP 200.
curl --fail-with-body 'https://api.openaiav.com/v1/generations/TASK_ID' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY"

# Repeat step 2 after poll_after_ms until status is succeeded or failed.
# Never recreate a task whose status is submission_unknown.

# 3. After succeeded, download — success: HTTP 200 (or 206 with Range).
curl --fail-with-body --location 'https://api.openaiav.com/v1/generations/TASK_ID/content' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY" \
  --output 'result.mp4'

リクエストパラメータ

参照モード

first_frame

first_frame：参照画像が開始フレームとなり、構図を決定します。referenceImages はちょうど 1 件を送信します。aspectRatio はモデルの aspect_ratios から選び、カタログに adaptive がある場合はそれに固定されます（出力は参照画像に追従します）。 first_last_frame：referenceImages をちょうど 2 件送信します。配列の順序が先頭フレーム、次に末尾フレームとなり、その間はモデルが補完します。2 枚の画像は同じ寸法である必要はありません。フレームモードは omni_reference と併用できません。

{
  "model": "seedance-2.5-oa",
  "prompt": "A young woman finishes a letter and walks from a stone cottage into the morning sunlight",
  "resolution": "480p",
  "aspectRatio": "adaptive",
  "durationSeconds": 4,
  "referenceMode": "first_frame",
  "referenceImages": [
    "https://developers.openaiav.com/samples/seedance-letter-reference.webp"
  ],
  "generateAudio": false,
  "outputFormat": "mp4"
}

omni_reference

omni_reference：参照アセットは開始フレームにはならず、被写体・スタイル・シーンの一貫性を保ちます。referenceImages に加えて、対応モデルでは referenceVideos と referenceAudios も受け付けます。種類ごとの上限は下表のとおりで、カタログが宣言していない種類は送信時に 400 となります。プロンプトでは種類ごとの順序で @Image1、@Video1、@Audio1 のように指定します。

{
  "model": "seedance-2.5-oa",
  "prompt": "Keep the identity and outfit from @Image1; a young woman walks from a stone cottage into the morning sunlight",
  "resolution": "480p",
  "aspectRatio": "16:9",
  "durationSeconds": 4,
  "referenceMode": "omni_reference",
  "referenceImages": [
    "https://developers.openaiav.com/samples/seedance-letter-reference.webp"
  ],
  "generateAudio": false,
  "outputFormat": "mp4"
}

現在の対応状況

すべての動画モデルで統合方法は同一です：同じエンドポイント、同じフィールドで、モデルを変えるときは model を変更するだけです。差異はすべてカタログが宣言します。下表がそのカタログそのもので、モデルごとに対応する参照モードと各素材の受け入れ数を示します。カタログが宣言していない機能は送信時に明示的に拒否され、黙って無視されることはありません。

先頭フレームの詳細と末尾フレームの受け渡し

先頭フレームの詳細：first_frame と omni_reference は排他で、1 リクエストにつきどちらか一方のみを選択します。オムニ参照でもプロンプトで参照画像を開始画面に寄せることはできますが、先頭フレームの厳密な一致が必要な場合は、その画像を first_frame モードで送信してください。Seedance 2.5 では先頭フレームのタスクはアスペクト比が adaptive に固定されます（出力は先頭フレームに追従）。末尾フレームの受け渡し：作成時に returnLastFrame: true を指定すると、成功したタスクは last_frame_url も返します（動画と同じサイズのウォーターマークなし PNG、24 時間保持）。その URL をそのまま次のリクエストの first_frame の referenceImages に渡せば、事前登録なしで複数カットを連結できます。

参照動画の料金

• 長さを測定できる参照動画は固定価格で課金され、その金額を事前にプレビューできます。測定できない場合はプレビューを拒否し、請求はしません。
• POST /v1/generation-quotes で現在の価格をプレビューできます。URL 動画はタスク作成時に再測定・再計算され、作成レスポンスの reserved_usd が実際の金額です。quoteId は引き続き送信できますが、価格は固定されません。expires_at はプレビュー更新の目安です。
• モデルカタログが動画ごと・合計の時間、本数、最低課金秒数を定めます。参照動画 1 本あたりの長さは、Seedance 2.0 シリーズが 2〜15 秒、その他の対応モデルが 2〜30 秒です。実測時間がモデルの範囲外なら 422 REFERENCE_DURATION_OUT_OF_RANGE を返し、課金されません。
• MP4/MOV の公開 HTTPS 直リンクを使用してください。判明したファイルサイズが 200 MiB を超える場合は REFERENCE_VIDEO_TOO_LARGE を返します。サイズが不明でも見積もれます。非公開 URL は REFERENCE_URL_NOT_PUBLIC、測定枠が満杯なら 429 REFERENCE_PROBE_BUSY です。コンソールへのアップロード上限は 32 MiB です。
• すべてのタスクは作成時に見積額の reserved_usd が請求され、成功時はその金額どおり、失敗時は全額返金されます。プレビューの price_usd は、その時点で作成した場合の請求額と同じです。出力時間は明示し、-1 は使えません。
• 公開動画 URL はプレビュー時と作成時に測定し、その後プラットフォームへの保存やアセット登録なしで生成サービスに直接渡します。URL の内容を変更しないでください。アップロードは別の登録経路を使います。実在人物の顔に関するモデルの制限は引き続き適用されます。

画像モデルの料金

• 画像モデルは 1 枚ごとの料金で、resolution と aspectRatio によって変わります（image_pricing.rates）。gpt-image-* と nano-banana-* のモデルの表示価格は、短いプロンプトで参照画像なしの場合の料金です。
• これらのモデルでは、参照画像を付けたりプロンプトが長かったりすると請求額が高くなります。タスクを作成する前に同じボディで POST /v1/generation-quotes を呼び出してください。返される price_usd が、現在の価格でのそのリクエストの請求額です。失敗したタスクは全額返金されます。

ポーリングとダウンロード

終了状態は succeeded と failed のみです。submission_unknown は受理状況の確認中、result_pending は結果の確定中です。元のタスク ID を保持してポーリングを続け、作成を再実行しないでください。成功後は、Open AIav 以外の場所に依存せず、認証付きの /content パスをご利用ください。結果は 24 時間保持されます（詳細レスポンスに output_expires_at が含まれます。期限切れのダウンロードは 410 OUTPUT_EXPIRED を返すため、早めに保存してください）。

廃止エンドポイントからの移行

エラーコード一覧

完全な一覧：HTTP ステータス、エラーコード、意味、推奨される対処、SDK のエラークラス。この表は SDK のエラーマッピングと同じデータを使用しています。未知の新しいコードは、SDK が HTTP ステータスに基づいて処理します。

画像タスクの失敗コード

画像タスクが status=failed で終了した場合は、error_code を読み取って下表と照合してください。失敗したタスクは全額返金されます。SDK は同じコードを持つ GenerationFailedError を送出します。

コンソールでのみ返されるコード