비디오 생성

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


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

요청 파라미터

파라미터	타입	필수	설명
`model`	string	✅	Model slug, 예: `bytedance/seedance-2.5` 또는 `bytedance/seedance-2.0`
`prompt`	string	✅	비디오의 텍스트 설명
`duration`	integer	—	비디오 길이（초）
`resolution`	string	—	`480p` / `720p` / `1080p` / `1K` / `2K` / `4K`
`aspect_ratio`	string	—	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `3:2` / `2:3` / `21:9` / `9:21`
`size`	string	—	정확한 픽셀 `WIDTHxHEIGHT`（예: `1280x720`）, `resolution` + `aspect_ratio`의 대안
`frame_images`	array	—	프레임 제어（image-to-video / first-and-last frame）. 존재하면 image-to-video로 처리됩니다. 아래 참조
`input_references`	array	—	주제 / 스타일 가이드（reference-to-video）이며, 정확한 프레임 anchor는 아닙니다. 아래 참조
`real_person`	boolean	—	기본값 `false`. 실존 인물 참조 이미지를 생성 전에 전처리하려면 `true`로 설정하며, 이미지 참조가 1개 이상 필요합니다
`generate_audio`	boolean	—	오디오 출력을 지원하는 모델에서는 기본값이 `true`
`seed`	integer	—	결정적 생성 seed（모든 공급자에서 보장되지는 않음）
`callback_url`	string	—	Terminal-state webhook URL, HTTPS여야 합니다（Webhooks 참조）
`provider`	object	—	`type`으로 제공 공급자를 지정하고 `options`로 공급자별 파라미터를 전달합니다. 공급자 라우팅 참조

`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가 반환됩니다.

`real_person`: 실존 인물 참조 이미지

Ofox의 한 단계 요청 흐름, Seedance 자산 등록과의 비교, 재시도 방법은 실제 인물 참조 이미지를 참고하세요.

참조 이미지에 식별 가능한 실존 인물이 포함된 경우 최상위 real_person 필드를 true로 설정하세요. Ofox는 생성 요청을 제출하기 전에 선택한 참조 필드의 모든 이미지에 개인정보 보호 전처리를 적용합니다. 기본값은 false이므로 기존 요청 동작은 바뀌지 않습니다.


{
  "model": "bytedance/seedance-2.0",
  "prompt": "인물이 영화 같은 야시장을 걷는다",
  "real_person": true,
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/person.jpg" }
    }
  ]
}

real_person은 frame_images 또는 input_references의 이미지와 함께 사용할 수 있지만 두 필드는 계속 상호 배타적입니다. 이미지 참조가 1개 이상 필요하며, 없으면 API가 400 invalid_request를 반환합니다.

전처리는 업스트림 안티 딥페이크 검사에서 발생하는 오탐을 줄일 수 있지만 콘텐츠 정책을 우회하거나 승인을 보장하지 않습니다. 공급자가 요청을 거부할 수 있으며, 거부된 작업에는 요금이 부과되지 않습니다. 입력을 수정하거나 다시 시도하세요. real_person 전처리 오류도 참조하세요.

생성 모드（암묵적）

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

모드	감지 조건
`text2video`	`frame_images`와 `input_references` 모두 없음
`img2video`	`frame_images`에 `first_frame` 하나 포함
`img2video_end`	`frame_images`에 `first_frame` + `last_frame` 포함
`imgref2video`	`input_references`, 이미지만 포함
`mixref2video`	`input_references`에 image / audio / video 혼합

응답

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


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

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

요청 예시

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

텍스트에서 비디오

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

Terminal


# 선택: 공급자 지정. 생략하면 플랫폼이 자동으로 라우팅합니다
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.5",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

이미지에서 비디오

frame_images에 first_frame 하나 포함 → 시작 이미지에서 애니메이션 생성.

Terminal


# 선택: 공급자 지정. 생략하면 플랫폼이 자동으로 라우팅합니다
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Make the dog in the frame start running",
    "duration": 5,
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/dog.jpg" },
        "frame_type": "first_frame"
      }
    ]
  }'

첫/마지막 프레임

frame_images에 first_frame + last_frame 포함 → 두 프레임 사이를 보간.

Terminal


# 선택: 공급자 지정. 생략하면 플랫폼이 자동으로 라우팅합니다
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Smoothly transition between the two frames",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/start.jpg" }, "frame_type": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/end.jpg" },   "frame_type": "last_frame" }
    ]
  }'

이미지 참조

input_references에 이미지만 포함（주제 / 스타일을 가이드하며 frame anchors는 아님）— 최대 9개.

Terminal


# 선택: 공급자 지정. 생략하면 플랫폼이 자동으로 라우팅합니다
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "This character skiing down a snowy mountain",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/style-ref.jpg" } }
    ]
  }'

혼합 참조

input_references에 image / audio / video 혼합（image ≤ 9 · audio ≤ 3, 각 ≤ 15s · video ≤ 1）.

Terminal


# 선택: 공급자 지정. 생략하면 플랫폼이 자동으로 라우팅합니다
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Have the character speak in the tone of this voice clip, in the style of this reference video",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } },
      { "type": "video_url", "video_url": { "url": "https://example.com/style-ref.mp4" } }
    ]
  }'

조합 가능한 옵션

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

Webhook (callback_url)

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


{
  "model": "bytedance/seedance-2.5",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

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

공급자 지정 (provider.type)

공급자별 파라미터（예: watermark）를 provider.options.<slug>로 전달합니다.


{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": { "dashscope": { "watermark": false } }
  }
}

정확한 픽셀 크기

resolution + aspect_ratio 대신 size로 정확한 픽셀을 지정합니다.


{
  "model": "bytedance/seedance-2.5",
  "prompt": "...",
  "size": "1280x720"
}

오디오 + seed

최상위 provider.type으로 작업을 한 공급자에 고정합니다. 자세한 내용은 공급자 라우팅을 참고하세요.

비디오 생성

요청 파라미터

frame_images[] 요소

input_references[] 요소

real_person: 실존 인물 참조 이미지

생성 모드（암묵적）

응답

요청 예시

텍스트에서 비디오

이미지에서 비디오

첫/마지막 프레임

이미지 참조

혼합 참조

조합 가능한 옵션

Webhook (callback_url)

공급자 지정 (provider.type)

정확한 픽셀 크기

오디오 + seed

`frame_images[]` 요소

`input_references[]` 요소

`real_person`: 실존 인물 참조 이미지