메인 콘텐츠로 건너뛰기
POST
비동기 API입니다. 제출 후 data[0].task_id를 읽고 작업 상태 조회로 결과를 확인하세요. 보통 1–3분이 걸리며 5–10초 간격으로 조회하는 것이 좋습니다. 실제 소요 시간은 작업에 따라 달라집니다.

모드 선택

요청 헤더

string
필수
Bearer <token> 형식의 Bearer 인증을 사용합니다. <token>은 APIMart API 키입니다. 본문은 Content-Type: application/json으로 전송합니다.

요청 매개변수

string
필수
apimart-zoe로 고정합니다.
string
최대 204,800자. 텍스트 기반 생성에는 필수이며 미디어만 전달할 때는 생략할 수 있습니다. draft_task_id로 최종 영상을 생성할 때는 전달할 수 없고 초안의 프롬프트를 그대로 사용합니다.
string
480p, 720p, 1080p, 2k, 4k를 지원하며 대소문자를 구분하지 않습니다. 일반 생성의 기본값은 720p입니다. draft: true는 480p만 지원하며 생략해도 480p입니다. draft_task_id는 1080p만 지원하며 생략해도 1080p입니다.
string
21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive를 지원합니다. 기본값은 모델 또는 미디어가 결정하는 adaptive입니다. 최종 영상에서는 생략하며 초안의 화면비를 따릅니다.동영상 편집(edit)에서는 생략하거나 adaptive만 전달하며 원본 화면비를 따릅니다.
string
aspect_ratio의 다른 이름이며 같은 값을 지원합니다. 둘 중 하나만 보내는 것을 권장합니다. 최종 영상 생성 시 생략하세요.
integer
일반 생성: 4–30 정수 초, 기본값 5. 지정값 또는 기본값으로 과금하며 완성된 영상 길이로 조정하지 않습니다. -1이면 모델이 결정합니다. 제출 시 30초분을 선차감하고 완료 후 실제 길이를 정수 초로 반올림해 정산합니다. 최종 영상에서는 생략하며 초안 길이를 따릅니다.동영상 편집(edit)에서는 생략하거나 -1만 전달하세요. 생략 시에도 -1로 처리하며 출력 길이는 원본을 따릅니다.
integer
duration의 별칭으로 동일한 규칙이 적용됩니다. 둘 중 하나만 사용하세요. 최종 영상 생성 시 생략합니다.
boolean
동영상과 함께 오디오를 생성할지 정하는 불리언 값입니다. 별칭은 generate_audio이며 생략하면 모델이 결정합니다. 최종 영상 생성 시 전달할 수 없습니다. 입력 참조인 audio_urls와 달리 출력 오디오를 제어합니다.audio와 generate_audio를 모두 전달하면 값이 같아야 하며 다르면 HTTP 400입니다. 생략하면 모델이 결정하며 보통 소리를 포함합니다.
boolean
audio의 별칭으로 같은 규칙을 적용합니다. 둘 중 하나만 사용하고 최종 영상에서는 생략하세요.audio와 generate_audio를 모두 전달하면 값이 같아야 하며 다르면 HTTP 400입니다. 생략하면 모델이 결정하며 보통 소리를 포함합니다.
integer
정수형 랜덤 시드입니다. 최종 영상 생성 시 전달할 수 없습니다.
boolean
기본적으로 심사하지 않습니다. true로 활성화합니다.선택적 불리언 값입니다. true이면 prompt, image_urls, image_with_roles, 첫·마지막 프레임 이미지, asset:// 이미지 미디어를 심사합니다. 참조 동영상과 오디오는 심사하지 않습니다.최종 영상 요청에는 프롬프트와 미디어가 없으므로 초안 → 최종 영상 흐름에서는 초안 생성 시 심사합니다.감지 시 HTTP 400(nsfw_content_detected)을 반환하고 error.message에 감지 범주를 포함합니다. 일반 매개변수 오류가 아니라 심사 거부로 표시하세요. 심사 서비스 오류나 호출 실패 시 생성 요청을 계속 제출하므로 이 설정이 모든 요청의 심사 완료를 보장하지는 않습니다.
string
auto(기본값, 생략과 같으며 모델이 판단), reference, edit를 지원합니다. reference / edit는 참조 미디어가 있어야 하며 텍스트 전용 또는 첫·마지막 프레임 요청에서는 HTTP 400입니다. edit는 video_urls에 최소 1개가 필요하고 draft: true와 함께 사용할 수 없습니다. extend는 미지원이며 HTTP 400을 반환합니다. 최종 영상 생성에는 전달하지 마세요.
boolean
true로 설정하면 마지막 프레임의 PNG 이미지를 data.result.last_frame_url로 추가 반환합니다. 기본적으로 반환하지 않습니다. 최종 영상 생성에는 전달하지 마세요.
string
mp4(기본값) 또는 mov(QuickTime 컨테이너)를 지원하며 다른 값은 HTTP 400입니다. 별칭은 response_format이며 둘 다 전달하면 output_format이 우선합니다. 최종 영상 생성에는 전달하지 마세요.
string
output_format의 별칭으로 mp4 / mov를 지원합니다. 둘 다 전달하면 output_format이 우선합니다. 최종 영상 생성에는 전달하지 마세요.
boolean
true이면 생성 전에 프롬프트를 자동 최적화합니다. 기본적으로 최적화하지 않고 원본 프롬프트를 사용합니다. 최종 영상 생성에는 전달하지 마세요.
object[]
각 항목은 url과 role을 포함합니다. 역할은 first_frame(첫 프레임), last_frame(마지막 프레임), reference_image(참조 이미지)입니다. 첫·마지막 프레임은 각각 최대 1장이고 마지막 프레임에는 첫 프레임이 필요합니다. 첫·마지막 프레임은 참조 미디어와 함께 사용할 수 없습니다.image_urls와 image_with_roles는 함께 전달할 수 없습니다. 함께 보내면 제출 시 HTTP 400(invalid_request_error)을 반환하며 과금하지 않습니다. 별칭 image, images, image_url도 image_urls로 처리하므로 이 제한을 우회할 수 없습니다.
string[]
참조 이미지 최대 30장. 형식·크기·파일 용량은 아래 미디어 요구 사항을 확인하세요.image_urls와 image_with_roles는 함께 전달할 수 없습니다. 함께 보내면 제출 시 HTTP 400(invalid_request_error)을 반환하며 과금하지 않습니다. 별칭 image, images, image_url도 image_urls로 처리하므로 이 제한을 우회할 수 없습니다.
string
첫 프레임 이미지 주소. image_with_roles의 first_frame 역할과 같습니다.
string
마지막 프레임 이미지 주소. image_with_roles의 last_frame 역할과 같습니다. 첫 프레임도 필요합니다.
string[]
참조 동영상 최대 10개. 공개 http(s) URL 또는 asset://<미디어 ID>를 지원하며 data: Base64는 지원하지 않습니다. 제출 시 아래 규칙으로 동영상 크기, 정확한 길이, 프레임률을 검사합니다.과금 시에는 각 길이를 합산한 후 정수 초로 내림하며 이후 조정하지 않습니다. 이 내림은 개별 동영상 길이의 유효성 검사에는 사용하지 않습니다. 접근이나 길이 확인에 실패하면 HTTP 400(input_video_probe_failed)을 반환하며 과금하지 않습니다.auto / reference: 2–15초, 허용 범위 1.8 ≤ t ≤ 15.2초. edit 원본 동영상: 4–30초, 허용 범위 3.8 ≤ t < 30.2초. 반올림하지 않은 정확한 길이로 검사합니다.
string[]
최대 10개, WAV / MP3. 각 2–15초 및 ≤ 15 MB, 합계 30초 이하. ±0.2초 허용 오차로 개별 1.8 ≤ t ≤ 15.2초, 합계 ≤ 30.2초를 허용합니다. 참조 이미지 또는 동영상이 필요합니다.공개 http(s) URL 또는 asset://<미디어 ID>를 지원하며 data: Base64는 지원하지 않습니다. 오디오 길이는 제출 시 검사하고 조건 위반 시 동기 HTTP 400을 반환하며 과금하지 않습니다.
boolean
true이면 480p 초안을 생성합니다. 나머지 매개변수는 일반 생성 규칙을 따릅니다. 최종 영상 요청에는 이 필드를 전달하지 마세요.동영상 편집(edit)은 초안을 생성할 수 없습니다.
string
성공한 초안의 task_id로 1080p 최종 영상을 생성합니다. 초안 생성 후 24시간 이내에 사용해야 합니다. 프롬프트·미디어·길이·화면비를 그대로 사용하므로 해당 필드를 다시 전달할 수 없습니다. 최종 영상 생성 시 seed, audio, 별칭 generate_audio도 전달할 수 없습니다.

미디어 주소 및 조합 제한

이미지·동영상·오디오는 공개 http(s) URL 또는 APIMart의 asset://<미디어 ID>를 지원합니다. 모두 data: Base64는 지원하지 않으므로 먼저 업로드하세요. 미디어 등록은 자동으로 처리되며 별도 API 호출이 필요 없습니다. 등록 실패 시 작업이 실패하고 환불됩니다.

참조 동영상 검사 규칙

동영상 크기, 픽셀 면적, 화면비, 정확한 길이와 프레임률 및 참조 오디오 길이를 제출 시 검사합니다. 조건 위반 시 동기 HTTP 400이며 과금하지 않습니다. 동영상 규격 오류는 invalid_request_error이며 실측값을 포함합니다. 짧은 변 480 이상·긴 변 4096 이하가 아닌 픽셀 면적으로 판단하세요. 크기만 보면 420×1000(420,000픽셀)은 허용됩니다. 720×480(345,600픽셀), 848×480(407,040픽셀), 4096×2160(8,847,360픽셀)은 면적 조건을 충족하지 못합니다. 길이·프레임률 등 다른 조건도 충족해야 합니다. 이미지 크기, 파일 용량, 인코딩은 생성 단계에서 검사합니다. 조건 위반 시 작업이 실패하고 자동 환불됩니다. 가능한 항목은 API 호출 전에 검사하세요.

미디어 조합 규칙

  • image_urls와 image_with_roles는 함께 전달할 수 없습니다. 함께 보내면 제출 시 HTTP 400(invalid_request_error)을 반환하며 과금하지 않습니다. 별칭 image, images, image_url도 image_urls로 처리하므로 이 제한을 우회할 수 없습니다.
  • 첫·마지막 프레임과 참조 이미지·동영상·오디오는 같은 요청에 포함할 수 없습니다.
  • 첫·마지막 프레임은 각각 최대 1장입니다. 마지막 프레임에는 첫 프레임이 필요합니다.
  • 참조 이미지 최대 30장, 동영상 최대 10개, 오디오 최대 10개이며 전체 미디어 합계는 최대 50개입니다.
  • 조합 또는 개수 제한을 위반하면 제출 시 동기적으로 HTTP 400을 반환하며 과금하지 않습니다.
  • omni_reference_task_type: "edit"에는 원본 동영상이 최소 1개 필요합니다(3.8 ≤ t < 30.2초). duration / seconds는 생략 또는 -1, aspect_ratio / size는 생략 또는 adaptive만 허용합니다. draft: true와 함께 사용하지 마세요. auto/reference에는 2–15초와 해당 허용 오차가 적용됩니다.
다음 필드는 값이 "", [], false, null이어도 존재하면 HTTP 400입니다. 필드 전체를 제거하세요: negative_prompt, camera_fixed, camerafixed, extend_from_task_id, mask_url, video_list, element_list, multi_shot, tools. n은 생략하거나 1만 전달하세요.

요청 예제

아래 미디어 URL은 예시입니다. 실제로 접근 가능한 미디어 주소로 바꾸세요.

첫·마지막 프레임

first_frame_image와 last_frame_image로도 지정할 수 있습니다. 같은 요청에 참조 이미지·동영상·오디오를 추가하지 마세요.

이미지·동영상·오디오 참조

image_urls의 이미지는 참조 이미지로 처리합니다. duration: -1이면 모델이 출력 길이를 결정합니다.

동영상 편집

omni_reference_task_type: "edit"에는 원본 동영상이 최소 1개 필요합니다(3.8 ≤ t < 30.2초). duration / seconds는 생략 또는 -1, aspect_ratio / size는 생략 또는 adaptive만 허용합니다. draft: true와 함께 사용하지 마세요. auto/reference에는 2–15초와 해당 허용 오차가 적용됩니다.
편집에는 참조 동영상 요금이 적용됩니다. 출력 30초를 선차감하고 완료 후 실제 출력 길이를 정수 초로 반올림하여 정산합니다. 아래 공식에 따라 참조 동영상 길이도 포함해 차액을 조정합니다.

마지막 프레임, MOV 출력 및 프롬프트 최적화

초안 → 최종 영상

  1. draft: true로 초안을 제출합니다. resolution을 생략하면 480p이며 명시하는 경우에도 480p만 지원합니다.
  1. 초안이 성공하면 해당 task_id로 최종 영상을 요청합니다. model과 draft_task_id만 필요합니다. resolution을 명시하려면 1080p를 사용하세요.
최종 영상은 초안의 프롬프트, 미디어, 길이, 화면비, 시드 및 오디오 설정을 상속합니다. model, draft_task_id, 선택적 resolution: "1080p", nsfw_check / webhook 같은 공통 필드만 전달하세요. 다음 생성 필드는 없어야 하며 빈 문자열·빈 배열·false·null도 HTTP 400입니다: prompt, image_urls, image_with_roles, image, images, image_url, first_frame_image, last_frame_image, video_urls, audio_urls, duration, seconds, aspect_ratio, size, seed, audio, generate_audio, draft, omni_reference_task_type, return_last_frame, output_format, response_format, enhance_prompt. 초안 생성 후 24시간 이내에 사용하며 두 생성은 별도 과금합니다.

작업 및 결과 조회

cURL
제출 응답의 data는 배열이고 조회 응답의 data는 작업 객체입니다. data.status는 pending(대기), processing(생성 중), completed(성공), failed(실패)입니다. 성공 시 data.result.videos[].url 배열에서 주소를 읽습니다. 예: data.result.videos[0].url[0]. 동영상은 APIMart 저장소로 복사됩니다. 아래는 성공한 조회의 주요 필드만 보여 줍니다.
작업 실패 시 data.error.message에서 원인을 확인하세요. 차감 금액은 자동 환불됩니다.

과금 규칙

출력 해상도와 참조 동영상 유무에 따라 초 단위로 과금합니다. 단가와 계정 할인은 가격 페이지를 확인하세요. D는 과금에 사용하는 출력 길이(초)입니다.
  • 참조 동영상 총길이 R: 제출 시 각 길이를 확인하고 합산한 다음 정수 초로 내림합니다. 이후에는 조정하지 않습니다.
  • 참조 동영상이 없으면 과금 초 = D. 있으면 과금 초 = D + max(R, ceil(D × 2/3)). ceil은 정수로 올림합니다. 참조 동영상이 있는 경우의 단가를 사용합니다.
  • 예: 8초 요청은 결과가 8.2초여도 D = 8입니다. 자동 길이 결과가 8.5초면 D = 9입니다. 참조 영상 2.8초와 3.8초는 합계 6.6초를 내림해 R = 6입니다.
  • 초안은 480p, 최종 영상은 1080p로 각각 과금합니다. 초안에 참조 동영상이 있으면 최종 영상에도 원래 참조 길이를 포함하며 재업로드할 필요는 없습니다.
  • 제출 실패는 과금하지 않으며 작업 실패 시 자동 환불됩니다.

일반적인 오류

제출 실패 시 error 객체를 반환합니다. 설명은 error.message, 문자열 오류 코드는 error.code이며 HTTP 상태 코드와 다릅니다. 제출 실패는 과금하지 않습니다.