Skip to Content
API 레퍼런스동영상 생성동영상 작업 생성

비디오 생성

비디오 생성 작업을 제출합니다. 요청은 작업 id와 polling URL을 포함해 즉시 202 Accepted를 반환하며, 생성은 비동기로 실행됩니다. 작업을 폴링하거나 webhook을 받은 뒤 비디오 상태 조회로 결과를 읽으세요.

POST https://api.ofox.ai/v1/videos

요청 파라미터

파라미터타입필수설명
modelstring✅Model slug, 예: google/veo-3.1 또는 bytedance/seedance-2.0
promptstring✅비디오의 텍스트 설명
durationinteger—비디오 길이（초）
resolutionstring—480p / 720p / 1080p / 1K / 2K / 4K
aspect_ratiostring—16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21
sizestring—정확한 픽셀 WIDTHxHEIGHT（예: 1280x720）, resolution + aspect_ratio의 대안
frame_imagesarray—프레임 제어（image-to-video / first-and-last frame）. 존재하면 image-to-video로 처리됩니다. 아래 참조
input_referencesarray—주제 / 스타일 가이드（reference-to-video）이며, 정확한 프레임 anchor는 아닙니다. 아래 참조
generate_audioboolean—오디오 출력을 지원하는 모델에서는 기본값이 true
seedinteger—결정적 생성 seed（모든 공급자에서 보장되지는 않음）
callback_urlstring—Terminal-state webhook URL, HTTPS여야 합니다（Webhooks 참조）
providerobject—공급자별 passthrough, Provider passthrough 참조

frame_images[] 요소

각 요소는 출력의 프레임 하나를 고정합니다. frame_type은 first_frame 또는 last_frame입니다.

{
  "type": "image_url",
  "image_url": { "url": "https://example.com/first.jpg" },
  "frame_type": "first_frame"
}

input_references[] 요소

type별로 이미지 / 오디오 / 비디오 참조를 전달합니다. 이는 주제, 스타일, 일관성을 가이드하며, 정확한 프레임 anchor는 아닙니다:

{ "type": "image_url", "image_url": { "url": "https://example.com/subject.jpg" } }
{ "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } }
{ "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" } }
미디어type최대 개수기타 제약
이미지image_url≤ 9—
오디오audio_url≤ 3클립당 ≤ 15s
비디오video_url≤ 1—

제한을 초과하면 400 too_many_references가 반환됩니다（Errors 참조）.

frame_images와 input_references는 상호 배타적입니다. 하나의 요청에서는 둘 중 하나만 사용해야 하며, 둘 다 전송하면 400 references_conflict가 반환됩니다.

생성 모드（암묵적）

gen_mode 필드는 없습니다. 어떤 입력을 보내는지에 따라 모드가 추론됩니다:

모드감지 조건
text2videoframe_images와 input_references 모두 없음
img2videoframe_images에 first_frame 하나 포함
img2video_endframe_images에 first_frame + last_frame 포함
imgref2videoinput_references, 이미지만 포함
mixref2videoinput_references에 image / audio / video 혼합

응답

202 Accepted — 작업이 status: "pending" 및 polling_url과 함께 수락됩니다:

{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "pending",
  "polling_url": "https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}

작업이 terminal state에 도달할 때까지 polling_url을 폴링하거나 webhook을 기다리세요. 비디오 상태 조회를 참조하세요.

요청 예시

하나의 /v1/videos 스키마가 모든 생성 모드를 처리하며, 모드는 입력값에 따라 암묵적으로 선택됩니다. 아래 예시는 각각 그대로 실행할 수 있습니다.

frame_images / input_references 없음 → text-to-video.

Terminal
curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

조합 가능한 옵션

아래 필드는 생성 모드와 독립적입니다. 위 요청 body 어디에든 추가할 수 있습니다.

폴링 대신 작업이 terminal state에 도달했을 때 사용자의 엔드포인트에서 POST를 수신합니다.

{
  "model": "google/veo-3.1",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

callback_url은 HTTPS여야 합니다. payload와 signature는 Webhooks를 참조하세요.

Provider passthrough

공급자별 파라미터는 provider.options.<slug>를 통해 전달되며, 매칭된 공급자만 이를 수신합니다. watermark 같은 파라미터는 모든 모델에서 지원되지 않으므로 top-level 필드가 아니라 provider passthrough에 둡니다（이는 OpenRouter의 provider-passthrough 규칙을 따릅니다）. 모델이 어떤 passthrough 옵션을 수락하는지는 해당 모델의 기능에 따라 달라집니다.

{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": {
      "dashscope": { "watermark": false, "audio_setting": "..." }
    }
  }
}
Last updated on
개요작업 조회