公式 SDK クイックスタート

The official SDKs wrap the one-step contract (create → poll → download) with automatic idempotency keys and typed errors; the Node SDK has zero dependencies and Python depends only on httpx. Distributed as GitHub repositories for now — npm/PyPI releases will be announced separately.

Node

npm install github:openaiav/sdk-node   # npm 正式发布另行公告

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 正式发布另行公告

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_...'
export OPENAIAV_IDEMPOTENCY_KEY='openaiav-quickstart-4s-480p-001'

すべてのリクエストで Authorization: Bearer oav_... を送信し、キーはサーバー側に保管してください。作成には generation:create、ポーリングとダウンロードには generation:read が必要です。ネットワークの結果が不明な場合は元の Idempotency-Key を再利用してください。同じキーを異なるボディと組み合わせてはいけません。

Request headers

エンドポイント一覧

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

モデルの対応状況をハードコードしないでください。reference_modes に記載されたモードのみを送信し、非対応の組み合わせは送信前に非表示または無効化してください。最小構成のサンプルは seedance-2.5 で 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 both values in environment variables; do not paste secrets into shell history.
# Generate OPENAIAV_IDEMPOTENCY_KEY once for this create intent and keep it unchanged on every retry.
# Set it before the first create, then reuse the exact value after a lost response.
# 1. Create — success: HTTP 201. On failure, the response body contains error.code.
curl --fail-with-body --request POST 'https://api.openaiav.com/v1/generations' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY" \
  --header "Idempotency-Key: $OPENAIAV_IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "女孩写完一封信，从乡间石屋走入清晨阳光",
  "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 がある場合はそれに固定されます(出力は参考画像に追従します)。\n\nfirst_last_frame:referenceImages をちょうど 2 件送信します。配列の順序が先頭フレーム、次に末尾フレームとなり、その間はモデルが補完します。2 枚の画像は同じ寸法である必要はありません。フレームモードは omni_reference と併用できません。

{
  "model": "seedance-2.5",
  "prompt": "女孩写完一封信，从乡间石屋走入清晨阳光",
  "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 となります。プロンプトでは種類ごとの順序で @画像1、@動画1、@音声1 のように指定します。

{
  "model": "seedance-2.5",
  "prompt": "@Image1 保持人物身份与服装一致，女孩从乡间石屋走入清晨阳光",
  "resolution": "480p",
  "aspectRatio": "16:9",
  "durationSeconds": 4,
  "referenceMode": "omni_reference",
  "referenceImages": [
    "https://developers.openaiav.com/samples/seedance-letter-reference.webp"
  ],
  "generateAudio": false,
  "outputFormat": "mp4"
}

Live compatibility

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

First-frame details & last-frame relay

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

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

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

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

エラーコード一覧

Full reference: HTTP status, code, meaning, suggested handling, and the SDK error class. This table shares its data source with the SDK error map; unknown new codes fall back by HTTP status in the SDK.

Console-session-only codes