공식 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. prompt, referenceMode, referenceImages를 /v1/generations로 POST합니다. 참조 이미지는 공개 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은 참조 이미지 한 장과 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에는 정확히 하나만 보내세요. aspectRatio는 모델의 aspect_ratios에서 고르며, 카탈로그에서 제공하면 adaptive로 고정됩니다(출력은 참조 이미지를 따릅니다). first_last_frame: referenceImages를 정확히 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는 함께 쓸 수 없으므로 요청마다 하나만 선택합니다. 멀티모달 참조에서도 프롬프트로 참조 이미지를 첫 장면 쪽으로 유도할 수 있지만, 첫 프레임이 정확히 같아야 한다면 그 이미지를 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는 새로고침 시각만 제안합니다.
• 모델 카탈로그는 동영상별 및 총 길이, 개수와 최소 청구 시간을 정합니다. 참조 동영상 한 개의 길이는 Seedance 2.0 시리즈가 2~15초, 그 밖의 지원 모델이 2~30초입니다. 측정된 동영상이 한도를 벗어나면 요금 없이 422 REFERENCE_DURATION_OUT_OF_RANGE를 반환합니다.
• 공개 HTTPS MP4/MOV 직접 링크를 사용하세요. 알려진 파일 크기가 200 MiB를 넘으면 REFERENCE_VIDEO_TOO_LARGE를 반환하며 크기를 알 수 없어도 견적을 받을 수 있습니다. 비공개 URL은 REFERENCE_URL_NOT_PUBLIC, 측정 중 혼잡은 429 REFERENCE_PROBE_BUSY입니다. 콘솔 업로드 한도는 32 MiB입니다.
• 모든 작업은 생성 시 견적 금액인 reserved_usd가 청구되며, 성공하면 그 금액 그대로이고 실패하면 전액 환불됩니다. 미리보기의 price_usd는 그 시점에 생성하면 청구될 금액과 같으며 출력 길이는 -1 대신 명시해야 합니다.
• 공개 동영상 URL은 미리보기와 생성 시 각각 검사한 뒤 저장이나 에셋 등록 없이 생성 서비스에 직접 전달됩니다. 내용을 안정적으로 유지하세요. 업로드는 별도 경로를 사용하며 실제 인물 얼굴 제한은 그대로 적용됩니다.

이미지 모델 가격

• 이미지 모델은 장당 가격이며 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를 발생시킵니다.

콘솔에서만 반환되는 코드