Seedance 시리즈

ByteDance의 동영상 생성 모델로 모두 네 가지이며, OfoxAI 동영상 API POST /v1/videos로 호출합니다. 작업은 비동기로 실행됩니다. 작업을 생성하면 작업 ID를 받고, 그 ID로 결과를 조회합니다.

모델 선택

핵심4K 출력이 필요하면 2.0, 30초 길이나 21:9 화면비가 필요하면 2.5, 480p·720p 동영상을 대량으로 생성하려면 Mini 또는 Fast를 선택하십시오.

모델	해상도（기본값）	길이	화면비
Seedance 2.5	`480p` `720p` `1080p`（`720p`）	4–30초	`21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive`
Seedance 2.0	`480p` `720p` `1080p` `4k`（`1080p`）	4–15초	`16:9` `9:16` `1:1` `adaptive`
Seedance 2.0 Fast	`480p` `720p`（`720p`）	4–15초	2.0과 동일
Seedance 2.0 Mini	`480p` `720p`（`720p`）	4–15초	2.0과 동일

네 모델 모두 텍스트-투-비디오, 이미지-투-비디오, 동영상 참조를 지원하며, 동기화된 오디오 트랙을 생성할 수 있습니다（generate_audio 기본값 true）. adaptive는 입력 이미지의 비율을 그대로 사용한다는 뜻입니다.

모델 ID（호출 시 그대로 복사）

Seedance 2.5bytedance/seedance-2.530초, 21:9

Seedance 2.0bytedance/seedance-2.04K

Seedance 2.0 Fastbytedance/seedance-2.0-fast480p, 720p

Seedance 2.0 Minibytedance/seedance-2.0-mini480p, 720p

위 표는 Models API가 반환하는 video_attributes와 일치합니다. 모델 기능이 조정되면 API 반환값을 기준으로 하십시오. 초 단위로 과금되며 실제 비용은 작업 결과의 usage.video_cost를 기준으로 합니다. 가격은 모델 페이지 를 참고하십시오.

resolution과 duration을 명시적으로 전달하십시오. 전달하지 않으면 2.0은 기본값이 1080p이며, 요금은 해상도 구간에 따라 계산되므로 720p보다 높아집니다.

호출 예시

핵심다섯 가지 생성 모드가 하나의 엔드포인트를 공유하며, 전달한 소재 필드로 모드가 결정되므로 모드 파라미터를 지정할 필요가 없습니다.

아래 예시는 작업 생성 요청만 보여 줍니다. 생성 후 상태 조회와 결과 다운로드까지의 전체 흐름은 Video API · 빠른 시작을 참고하십시오.

텍스트-투-비디오

prompt만 전달합니다.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0-mini",
    "prompt": "여우 한 마리가 눈밭을 달리고, 카메라가 뒤따라간다",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

이미지-투-비디오

frame_images에 first_frame 1장을 전달하면 해당 이미지를 첫 프레임으로 하는 동영상이 생성됩니다. 화면비를 adaptive로 설정하면 이미지 비율을 그대로 사용합니다.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "화면 속 강아지가 카메라를 향해 달려온다",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/dog.jpg" }, "frame_type": "first_frame" }
    ]
  }'

첫/마지막 프레임

frame_images에 first_frame과 last_frame을 전달하면 두 프레임 사이의 전환이 생성됩니다. last_frame만 전달하면 400이 반환됩니다.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "꽃봉오리가 천천히 피어나 활짝 핀 장미가 된다",
    "duration": 5,
    "resolution": "720p",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/bud.jpg" }, "frame_type": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/rose.jpg" }, "frame_type": "last_frame" }
    ]
  }'

참조 이미지

input_references에 이미지（최대 9장）를 전달해 인물, 상품, 스타일의 일관성을 유지하며, 고정 화면으로 쓰이지는 않습니다. 프롬프트에서는 「이미지 1」「이미지 2」처럼 각 이미지를 지칭하는 것을 권장합니다.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.5",
    "prompt": "이미지 1의 소녀가 이미지 2의 컵을 들고 카페 창가에서 미소 짓는다",
    "duration": 5,
    "resolution": "720p",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/girl.jpg" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/cup.jpg" } }
    ]
  }'

오디오·동영상 참조

input_references에는 이미지, 오디오（최대 3개, 각 15초 이하）, 동영상（최대 1개）을 섞어 전달할 수 있습니다. 동영상을 입력으로 사용하면 과금 초에 입력 동영상의 길이가 포함될 수 있습니다.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "캐릭터가 이 음성의 말투로 말하고, 카메라 스타일은 이 동영상을 참고한다",
    "duration": 5,
    "resolution": "720p",
    "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" } }
    ]
  }'

frame_images와 input_references는 함께 전달할 수 없으며, 함께 전달하면 400 references_conflict가 반환됩니다.
이미지는 공개 URL 또는 data:image/...;base64,로 시작하는 문자열을 사용할 수 있습니다.
오디오 트랙이 필요 없으면 "generate_audio": false를 전달합니다.
필드 구조의 전체 설명은 동영상 작업 생성을 참고하십시오.

실존 인물 참조 이미지

핵심OfoxAI를 통해 호출하면 Seedance 소재 라이브러리 인증을 거칠 필요 없이, 요청 최상위에 real_person: true만 추가하면 됩니다.

ByteDance 공식 Seedance API는 실존 인물의 얼굴이 포함된 참조 이미지나 동영상을 직접 업로드하는 것을 허용하지 않습니다. BytePlus Seedance 2.0 공식 문서 는 승인된 실존 인물 소재를 사용하도록 요구하며, Volcano Engine Ark 실존 인물 라이브러리 가이드 는 초대 발송, 본인 인증과 승인, 소재 업로드, 승인 수령과 소재 ID 획득 등의 단계를 안내합니다.

단계	Seedance 공식 API 직접 연결	OfoxAI를 통한 호출
첫 요청 전	소재 그룹 생성, 실존 인물 인증과 승인 완료, 소재 업로드와 검증, 소재 ID 획득	공급자 플랫폼에 사전 등록할 필요 없음
참조 이미지 전달	활성화된 승인 소재 `asset://<asset_id>` 사용	`frame_images` 또는 `input_references`에 이미지 URL 또는 `data:` URI 전달
요청 설정	심사를 통과한 소재 URI로 교체	요청 최상위에 `"real_person": true` 추가


{
  "model": "bytedance/seedance-2.0",
  "prompt": "화면 속 인물이 영화 같은 분위기의 야시장을 걸어간다",
  "duration": 5,
  "resolution": "720p",
  "real_person": true,
  "input_references": [
    { "type": "image_url", "image_url": { "url": "https://example.com/person.jpg" } }
  ]
}

OfoxAI는 제출 전에 참조 이미지에 개인정보 보호 전처리를 적용합니다. 업스트림 딥페이크 방지 심사의 오거부를 줄일 수 있지만, 업스트림의 수락을 보장하지는 않습니다. 업스트림에서 거부된 작업에는 요금이 부과되지 않습니다.
real_person은 처리 지시일 뿐 승인 증명이 아닙니다. 법적으로 사용할 권리가 있고 승인을 받은 이미지만 제출하십시오.
이미지가 계속 거부될 때의 조정 방법과 전처리 오류 코드는 실존 인물 참조 이미지를 참고하십시오.

공급자 지정

핵심Seedance는 두 공급자가 제공하며 심사 기준이 다릅니다. 지정하지 않으면 게이트웨이가 가중치에 따라 분배합니다.

공급자	설명	콘텐츠 심사
`volcengine`	Volcano Engine Ark, ByteDance의 중국 본토 플랫폼	표준 심사
`byteplus`	BytePlus, ByteDance의 해외 플랫폼	모든 연령대에 적합하지 않은（NSFW）콘텐츠 허용

공급자를 고정하려면 요청 최상위에 다음을 추가합니다.


"provider": { "type": "byteplus" }

모든 연령대에 적합하지 않은 콘텐츠를 생성해야 한다면 반드시 byteplus를 명시적으로 지정하십시오. 지정하지 않으면 요청이 volcengine으로 분배되어 콘텐츠 심사에서 거부될 수 있습니다. 공급자를 지정한 경우 해당 공급자를 사용할 수 없어도 요청이 자동으로 전환되지 않습니다.

provider.type 값이 잘못되면 400 invalid_provider_type이, 지정한 공급자가 해당 모델을 제공하지 않으면 400 provider_type_unavailable이 반환됩니다. 공통 설명은 동영상 공급자 라우팅을 참고하십시오.

자주 발생하는 오류

핵심파라미터 검증 오류는 생성 시점에 바로 반환되며, 작업이 생성되지 않고 비용도 발생하지 않습니다. 오류 메시지에 허용 값이 표시됩니다.

HTTP · code	오류 메시지 원문	원인	해결 방법
400 `unsupported_parameter`	`duration 3 out of range [4, 15]`	길이가 해당 모델의 범위를 벗어남	2.0 계열은 4–15초, 2.5는 4–30초
400 `unsupported_parameter`	`resolution "1080p" not supported; allowed: [480p 720p]`	Fast와 Mini는 1080p를 지원하지 않음	`720p`로 바꾸거나 2.0 / 2.5 사용
400 `unsupported_parameter`	`resolution "4k" not supported; allowed: [480p 720p 1080p]`	4K는 2.0만 지원	`bytedance/seedance-2.0` 사용
400 `unsupported_parameter`	`aspect_ratio "21:9" not supported; allowed: [16:9 9:16 1:1 adaptive]`	2.0 계열은 21:9를 지원하지 않음	2.5를 사용하거나 지원되는 비율로 변경
400 `references_conflict`	`frame_images and input_references are mutually exclusive`	두 가지 소재 필드를 함께 전달함	둘 중 하나만 선택. 호출 예시 참고
400 `invalid_request`	`frame_images: last_frame requires a first_frame`	마지막 프레임만 전달함	`first_frame` 추가
400 `too_many_references`	`input_references over limit: images 10/9, audios 0/3, videos 0/1`	참조 소재가 상한을 초과함	이미지 최대 9장, 오디오 최대 3개, 동영상 최대 1개
400 `invalid_request`	`real_person requires at least one image reference`	`real_person`을 활성화했지만 이미지를 전달하지 않음	이미지를 추가하거나 `real_person` 제거
400 `invalid_request`	`cannot unmarshal string into Go struct field CreateVideoRequest.duration of type int`	`duration`에 문자열（예: `"5s"`）을 전달함	정수（예: `5`）로 변경
400 `invalid_callback_url`	`callback_url must be a public HTTPS URL`	콜백 주소가 HTTPS가 아니거나 내부망 주소임	공개 HTTPS 주소로 변경
404 `model_not_found`	`model not found`	모델 ID 철자 오류（예: `bytedance/seedance-2`）	이 페이지에서 모델 ID 복사
402 `insufficient_credits`	—	잔액이 예상 비용보다 부족함（작업이 생성되지 않음）	충전 후 다시 시도

작업이 생성된 뒤 생성 단계에서 실패하면 조회 결과는 status: "failed"이며, 실패 원인은 error 필드에 있습니다. 시간 초과는 error.code: "expired"에 해당합니다. 전체 오류 코드는 Video API 오류 코드를 참고하십시오.

공식 문서

자주 묻는 질문

Seedance로 첫/마지막 프레임 동영상을 만들려면 어떻게 합니까?

frame_images에 이미지 두 장을 전달합니다. 한 장은 frame_type을 first_frame으로, 다른 한 장은 last_frame으로 지정합니다. last_frame만 전달하면 400 last_frame requires a first_frame이 반환됩니다. frame_images는 input_references와 함께 전달할 수 없습니다.

Seedance 2.0은 4K를 지원합니까?

4k는 bytedance/seedance-2.0만 지원합니다. 2.5는 최대 1080p, Fast와 Mini는 최대 720p이며, 지원하지 않는 해상도를 전달하면 400이 반환되고 오류 메시지에 허용 값이 표시됩니다.

Seedance로 최대 몇 초까지 생성할 수 있습니까?

Seedance 2.5는 작업 하나당 4초에서 30초, 2.0, 2.0 Fast, 2.0 Mini는 4초에서 15초입니다. 범위를 벗어나면 400 duration out of range가 반환됩니다.

Seedance는 21:9를 지원합니까?

21:9는 Seedance 2.5만 지원합니다. 2.0 계열은 16:9, 9:16, 1:1, adaptive만 지원합니다.

Seedance 참조 이미지에 실존 인물이 있어 오류가 나면 어떻게 합니까?

공식 API에 직접 연결하면 먼저 소재 라이브러리에서 본인 인증을 마쳐야 합니다. OfoxAI를 통해 호출하면 요청 최상위에 real_person: true를 추가해 이미지를 바로 전달할 수 있으며, OfoxAI가 먼저 개인정보 보호 전처리를 수행합니다. 그래도 업스트림에서 거부되면 요금이 부과되지 않으며, 실존 인물 참조 이미지 페이지의 권장 사항에 따라 이미지를 조정한 뒤 다시 시도할 수 있습니다.

Seedance에는 참조 이미지를 한 번에 몇 장까지 전달할 수 있습니까?

input_references에는 이미지 최대 9장, 오디오 최대 3개（각 15초 이하）, 동영상 최대 1개를 전달할 수 있습니다. 초과하면 400 too_many_references가 반환됩니다.

Seedance로 생성한 동영상 주소는 얼마 후에 만료됩니까?

mirror_urls를 우선 사용하십시오. unsigned_urls만 반환되었다면 업스트림의 임시 주소이므로 24시간 후 만료될 수 있으니, 바로 다운로드해 저장하십시오.