메인 콘텐츠로 건너뛰기
POST

인증

string
필수
모든 요청은 Bearer Token 인증이 필요합니다.API Key 발급:API Key 관리 페이지에서 API Key를 발급받으세요.요청 시 다음 헤더를 추가합니다:

요청 파라미터

string
필수
비디오 생성 모델 이름입니다. gemini-omni-1.2-flash-ext로 고정됩니다.
string
필수
비디오 내용 설명 또는 편집 지시입니다. 앞뒤 공백을 제거한 후 비어 있으면 안 됩니다. 텍스트-비디오에서는 장면, 인물, 동작, 카메라, 사운드를 설명하고, 이미지나 비디오를 함께 전달할 때는 동작, 스타일 또는 수정 내용을 설명합니다.예시: "Aerial shot over a misty mountain lake at sunrise."
첫 프레임, 다중 이미지 참조, 편집, 연장을 포함한 모든 모드에서 prompt는 필수입니다. 누락되면 400 오류가 반환됩니다.
integer
기본값:"10"
비디오 길이(초)이며 정수여야 합니다.
  • 텍스트-비디오 / 첫 프레임 / 다중 이미지 참조: 출력 길이, 3–15
  • 첫·마지막 프레임: 출력 길이, 3–10
  • 연장(extend): 새로 추가되는 구간의 길이, 3–10
  • 편집(edit): 전달할 수 없으며, 출력 길이는 원본 비디오를 따릅니다
별칭 seconds도 사용할 수 있습니다. 두 값을 함께 전달하면 같아야 합니다.
편집 모드에서 duration을 전달하면 video edit does not accept duration 오류가 반환됩니다.
string
기본값:"720p"
비디오 해상도입니다. 대소문자를 구분하지 않으며 초당 단가를 결정합니다.지원 값:
  • 360p
  • 720p
  • 1080p
  • 4k(2160p도 가능)
그 외 해상도를 전달하면 400 오류가 반환됩니다.
string
기본값:"16:9"
16:9(가로 화면, 기본값)와 9:16(세로 화면)만 지원하며, 그 외 값은 400 오류가 반환됩니다.
string
작업 유형으로, 소재를 사용하는 방식을 지정합니다.지원 값:
  • edit - 비디오 편집. video_urls 또는 extend_from_task_id와 함께 사용합니다
  • extend - 비디오 끝에 새 내용을 추가해 연장합니다. video_urls 또는 extend_from_task_id와 함께 사용합니다
  • reference - 다중 이미지 참조. image_urls와 함께 사용합니다
  • text_to_video / image_to_video / reference_to_video - 텍스트-비디오 / 첫 프레임 / 참조 이미지
  • auto - 입력에 따라 자동 판단하며, 비디오가 있으면 edit로 처리됩니다
비디오가 없으면 생략할 수 있으며, 입력에 따라 자동 판단됩니다.
video_urls 또는 extend_from_task_id를 전달할 때는 작업 유형(omni_reference_task_type 또는 호환 필드 generation_type)이 필수이며, 생략하면 400 오류가 반환됩니다. edit 또는 extend를 명시적으로 전달하는 것을 권장하며, auto는 edit로 처리됩니다.
string
호환 필드로, omni_reference_task_type과 동일합니다. 지원 값: frame(image_to_video와 동일), reference, edit, extend.
generation_type과 omni_reference_task_type은 함께 전달할 수 없습니다.
array<url>
다중 이미지 참조(인물, 상품, 스타일 등)용 참조 이미지 배열이며, 1–10장을 지원합니다.공개적으로 접근 가능한 HTTP/HTTPS 이미지 URL만 지원합니다. 로컬 이미지는 먼저 업로드하여 공개 URL을 받은 후 전달하세요. 현재 Base64 Data URL은 지원하지 않으며, 전달하면 400 오류가 반환됩니다.이미지를 1장만 전달하면 작업 유형에 따라 처리 방식이 달라집니다:
  • omni_reference_task_type 생략: 참조 이미지로 처리
  • omni_reference_task_type이 auto 또는 image_to_video: 첫 프레임으로 처리
첫 프레임 생성에는 이미지 개수에 의존하지 말고 first_frame_image를 직접 사용하는 것을 권장합니다.
image_urls는 first_frame_image 또는 last_frame_image와 함께 전달할 수 없으며, image_urls의 이미지는 첫 프레임으로 처리되지 않습니다. 편집 및 연장 시에도 이미지를 전달할 수 없습니다.
string
첫 프레임 이미지로, 생성된 비디오의 첫 프레임이 이 이미지가 됩니다. 공개적으로 접근 가능한 HTTP/HTTPS 이미지 URL만 지원하며, Base64 Data URL은 지원하지 않습니다.last_frame_image와 함께 전달하면 첫·마지막 프레임 기반 비디오 생성이 됩니다.
string
마지막 프레임 이미지로, 첫·마지막 프레임 기반 비디오 생성에 사용되며 비디오는 첫 프레임에서 이 이미지로 전환됩니다. 공개적으로 접근 가능한 HTTP/HTTPS 이미지 URL만 지원하며, Base64 Data URL은 지원하지 않습니다.첫·마지막 프레임 모드에서는:
  • duration은 3–10을 지원하며, 생략 시 10초
  • system_prompt와 negative_prompt를 전달할 수 없습니다
last_frame_image는 반드시 first_frame_image와 함께 전달해야 하며, 마지막 프레임만 전달하면 last_frame_image requires first_frame_image 오류가 반환됩니다. image_urls와 함께 전달할 수 없습니다.
array<object>
역할이 지정된 이미지 배열로, first_frame_image / last_frame_image / image_urls와 동일한 표기 방식입니다.
array<url>
편집 또는 연장할 비디오 배열로, 비디오 1개만 지원합니다. 단일 값 필드 video_url을 대신 사용할 수도 있으며, 둘 중 하나만 전달합니다.공개적으로 접근 가능한 HTTP/HTTPS 비디오 URL만 지원합니다. 형식은 MP4 / MOV / WebM이며, 길이 15초 이하, 크기 64 MB 이하입니다.
video_urls를 전달할 때는 작업 유형이 필수이며, omni_reference_task_type을 edit 또는 extend로 지정하는 것을 권장합니다(auto는 edit로 처리). 생략하면 400 오류가 반환됩니다. 비디오를 2개 이상 전달하면 400 오류가 반환됩니다.
string
본 플랫폼의 작업 ID(task_01…)입니다. 이전에 완료한 본인의 gemini-omni-1.2-flash-ext 작업을 기반으로 비디오를 다시 업로드하지 않고 편집 또는 연장을 이어갈 수 있습니다.사용 조건:
  • 작업이 현재 계정에 속해 있어야 합니다
  • 작업 모델이 gemini-omni-1.2-flash-ext여야 합니다
  • 작업 상태가 completed여야 합니다
  • 원본 작업을 생성한 채널을 계속 사용할 수 있어야 하며, 그렇지 않으면 503 source_channel_unavailable이 반환됩니다
  • 원본 결과물이 15초 이하여야 합니다(편집과 연장 모두 적용). 편집 모드에서는 길이를 식별할 수 있어야 합니다
채널을 사용할 수 없거나 원본 결과물의 길이를 식별할 수 없으면 원본 결과물을 다운로드한 후 video_urls로 업로드하세요. 원본 결과물이 15초를 초과하면 15초 이내로 자른 후 업로드하세요.
extend_from_task_id는 video_urls와 함께 전달할 수 없으며, 작업 유형이 필수입니다. omni_reference_task_type을 edit 또는 extend로 지정하는 것을 권장합니다(auto는 edit로 처리).
string
화면에 나타나지 않기를 원하는 내용입니다.예시: "people, cars, color"
첫·마지막 프레임 모드에서는 negative_prompt를 전달할 수 없습니다.
string
화면 스타일 고정, 텍스트 표시 금지 등의 시스템 지시입니다. 문자열이어야 합니다.예시: "Render as a black-and-white silent film."
첫·마지막 프레임 모드에서는 system_prompt를 전달할 수 없습니다.

응답

integer
응답 상태 코드입니다. 성공 시 200입니다.
array
작업 배열을 반환합니다.

작업 결과 조회

비디오 생성은 비동기 작업입니다. 제출 후 task_id가 반환되며, 작업 상태 조회 API로 생성 진행 상황과 결과를 조회합니다.
cURL
5-10초마다 폴링하고 클라이언트 타임아웃을 10분 이상으로 설정하는 것을 권장합니다. 생성 소요 시간 참고(대기 포함): 360p 15초 약 46초, 1080p 15초 약 99초, 4k 15초 약 4-5분. 생성 중에는 완료될 때까지 진행률이 오랫동안 10%에 머무를 수 있습니다.

성공 결과 예시

비디오 URL은 data.result.videos[0].url[0]입니다. data.actual_time은 작업 소요 시간(초)이며 비디오 길이가 아닙니다. 출력은 MP4(H.264, 24fps)이며 AAC 오디오 트랙과 SynthID 비가시 워터마크가 포함됩니다. 4k는 간혹 오디오 트랙이 없을 수 있습니다.

실패 결과 예시

작업이 실패하면 전액 환불됩니다.

과금 안내

초 단위 과금: 비용 = 선택한 해상도의 초당 단가 × 과금 초. 모든 모드는 요청한 해상도 등급으로 과금됩니다. 실제 단가는 가격 페이지를 확인하세요.

사용 사례

시나리오 1: 텍스트-비디오

시나리오 2: 첫 프레임 기반 비디오

시나리오 3: 첫·마지막 프레임 기반 비디오

첫·마지막 프레임 모드에서 duration은 3–10초를 지원하며 생략 시 10초입니다. system_prompt / negative_prompt는 전달할 수 없습니다.

시나리오 4: 다중 이미지 참조

시나리오 5: 비디오 편집

편집 시에는 duration을 전달하지 않으며, 출력 길이는 원본 비디오를 따릅니다.

시나리오 6: 비디오 연장

시나리오 7: 기존 작업 기반 연장

시나리오 8: 시스템 지시와 네거티브 프롬프트