apimart-zoe API

apimart-zoe는 APIMart의 멀티모달 영상 생성 모델로, 호출 시 모델 ID는 apimart-zoe입니다. apimart-zoe API는 텍스트-영상, 첫·마지막 프레임 영상, 이미지·영상·오디오 참조 영상 생성, 기존 영상 편집, 선택적인 오디오 동시 생성, 그리고 '480p 초안 → 1080p 최종본' 2단계 생성을 지원합니다. 영상은 4~30초이며 해상도는 480p, 720p, 1080p, 2k, 4k입니다.

Authorization: Bearer <API 키>를 붙여 model에 apimart-zoe와 프롬프트를 담아 POST /v1/videos/generations로 보냅니다. 응답으로 task_id가 반환됩니다. 생성에는 보통 1~3분이 걸리므로 data.status가 completed가 될 때까지 5~10초마다 GET /v1/tasks/{task_id}를 폴링한 뒤 data.result.videos[0].url[0]에서 영상 URL을 읽습니다. 이 페이지의 예제에 cURL과 Python 코드가 있으며, 전체 apimart-zoe API 레퍼런스는 APIMart 문서에서 확인할 수 있습니다.

model(apimart-zoe)은 필수입니다. prompt는 텍스트-영상에서 필수이고 소재만 보낼 때는 생략할 수 있으며 최대 204,800자입니다. 선택 파라미터는 resolution(480p, 720p, 1080p, 2k, 4k), aspect_ratio 또는 size(21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive), duration 또는 seconds(4~30 또는 -1), audio 또는 generate_audio, seed, image_with_roles, image_urls(별칭 image, images, image_url), first_frame_image, last_frame_image, video_urls, audio_urls, draft, draft_task_id, omni_reference_task_type(auto, reference, edit), return_last_frame, output_format 또는 response_format(mp4, mov), enhance_prompt, 그리고 APIMart 필드인 nsfw_check입니다. negative_prompt, camera_fixed(camerafixed 포함), extend_from_task_id, mask_url, video_list, element_list, multi_shot, tools는 지원하지 않으며, 빈 문자열·빈 배열·false·null이라도 필드가 요청에 있으면 400을 반환합니다. n은 생략하거나 1만 지정할 수 있습니다. 기본값과 제한은 이 페이지의 파라미터 표를 참고하세요.

duration(또는 seconds)을 4~30 사이의 정수로 지정합니다. 기본값은 5초이며 -1이면 모델이 길이를 정합니다. resolution은 480p, 720p(기본값), 1080p, 2k, 4k이고 대소문자를 구분하지 않습니다. aspect_ratio(size로도 지정 가능)는 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive(기본값, 모델이나 소재에 맞춰 결정)입니다. 영상 편집에서는 duration과 aspect_ratio를 생략하거나 -1과 adaptive로 보내며, 길이와 화면은 원본 영상을 따릅니다. 초안은 항상 480p, 최종본은 1080p입니다.

네. image_with_roles로 first_frame과 last_frame을 보내거나 first_frame_image와 last_frame_image를 사용하세요. 프레임마다 이미지는 1장이며, 마지막 프레임에는 첫 프레임이 필요합니다. 첫·마지막 프레임 요청에는 참조 이미지, 참조 영상, 참조 오디오를 함께 넣을 수 없으며, 넣으면 400이 반환되고 과금되지 않습니다. 두 프레임 사이의 카메라 움직임은 프롬프트로 설명하세요.

참조 이미지 최대 30장, 참조 영상 10개, 참조 오디오 10개로 소재는 합계 50개까지이며, 참조 오디오에는 참조 이미지나 참조 영상이 함께 있어야 합니다. 이미지는 jpeg, png, webp, bmp, tiff, gif, heic, heif이며 한 변 300~6000픽셀, 화면비 0.4~2.5, 장당 30MB 미만입니다. 영상은 mp4 또는 mov(H.264/H.265, 오디오 트랙 AAC 또는 MP3)로 개당 2~15초(1.8~15.2초 허용)·200MB 이하, 가로·세로 각각 300~6000픽셀, 가로×세로 409,600~8,295,044(약 640×640~3840×2160), 화면비 0.4~2.5, 프레임 레이트 24~60(반올림 후 판단, 23.976·59.94 가능)입니다. 영상 편집의 원본 영상은 4~30초(최소 3.8초, 30.2초 미만)까지 쓸 수 있으며, 작업 유형을 지정하지 않으면 15초를 넘는 영상은 edit를 사용해야 합니다. 오디오는 wav 또는 mp3로 개당 2~15초(1.8~15.2초)·15MB 이하, 합계 30초(30.2초) 이내입니다. 참조 영상의 길이·가로세로·화면비·프레임 레이트와 참조 오디오 길이는 제출 시 검사하며, 맞지 않으면 400 invalid_request_error를 반환하고 과금하지 않습니다. 이미지 크기, 파일 크기, 인코딩은 생성 시 검사하며, 맞지 않으면 작업이 실패하고 비용은 자동 환불되므로 호출 전에 직접 확인하세요. 모든 소재는 공개 http(s) URL이나 asset:// 소재 ID로 보내야 하며, data: URI는 받지 않으므로 먼저 공개 주소에 업로드하세요. 제출 시 APIMart가 소재를 자동 등록하며, 같은 파일을 7일 안에 다시 쓰면 중복 등록하지 않습니다. 소재만 보낼 때는 prompt를 생략할 수 있습니다.

먼저 draft: true로 요청을 보내 저비용 480p 미리보기를 만듭니다. 초안은 480p만 가능하며 영상 편집과 함께 쓸 수 없습니다. 초안이 성공하면 model과 draft_task_id(초안의 task_id)를 담은 두 번째 요청을 보냅니다. 최종본은 1080p로 생성되며 초안의 프롬프트, 소재, 길이, 화면비, 시드, 오디오 설정을 그대로 사용합니다. model, draft_task_id, resolution과 nsfw_check·webhook 같은 공통 필드 외에는 보낼 수 없으며, prompt, 소재, duration, aspect_ratio, seed, audio, omni_reference_task_type, return_last_frame, output_format, enhance_prompt는 빈 값이어도 400을 반환합니다. 최종본은 초안 생성 후 24시간 안에 만들어야 하며, 존재하지 않거나 초안이 아니거나 아직 완료되지 않았거나 24시간이 지난 draft_task_id는 400을 반환합니다. 초안과 최종본은 각각 한 번의 생성으로 과금되며, 최종본은 1080p로 초안의 길이(초안이 -1이었다면 초안의 실제 길이)만큼 과금됩니다.

제출 오류는 message, type, param, code를 담은 error 객체로 반환되며 과금되지 않습니다. 400 invalid_request_error는 값 오류, 소재 수와 조합(첫·마지막 프레임과 참조 소재 동시 사용, image_urls와 image_with_roles 동시 사용 등), 참조 영상의 길이·가로세로·화면비·프레임 레이트나 참조 오디오 길이 범위 초과, 작업 유형과 영상 편집 제약, output_format 값, 초안·최종본 제약, negative_prompt나 camera_fixed 같은 미지원 파라미터에 해당합니다. 400 input_video_probe_failed는 참조 영상에 접근할 수 없거나 길이를 확인할 수 없다는 뜻입니다. 402 payment_required는 잔액 부족이며, duration이 -1이거나 영상 편집이면 30초 기준으로 미리 차감합니다. 400 nsfw_content_detected는 nsfw_check 검수에 걸렸다는 뜻이며, message에 해당 카테고리가 표시됩니다. 503 draft_channel_unavailable 또는 draft_task_unavailable은 초안 기능을 일시적으로 쓸 수 없다는 뜻이니 잠시 후 다시 시도하거나 초안을 새로 만드세요.

보통 1~3분이 걸리므로 5~10초마다 조회하세요. data.status는 pending, processing, completed, failed 중 하나이고 data.progress는 0~100입니다. data.result.videos[0].url의 영상 URL은 APIMart 스토리지에 저장되어 있으며 완료 후 72시간이 지나면 만료되니 제때 내려받으세요. return_last_frame: true를 보내면 data.result.last_frame_url로 마지막 프레임 png 이미지도 받을 수 있습니다. 소재 등록이 통과되지 않았거나 생성 시 이미지 크기·파일 크기·인코딩 검사를 통과하지 못한 경우를 포함해 작업이 실패하면 data.error.message에 원인이 표시되고, data.error.code는 task_failed, data.cost는 0이 되며 미리 차감된 비용은 자동으로 환불됩니다.

apimart-zoe API는 출력 초 단위로 과금되며, 480p·720p·1080p·2k·4k별 단가와 참조 영상이 있는 요청용 단가가 따로 있습니다. duration(4~30)을 지정하거나 생략(기본값 5)하면 요청한 초 수로 과금되며 완료 후 영상 길이에 맞춰 조정되지 않습니다. duration이 -1이거나 영상 편집(omni_reference_task_type: edit)이면 30초 기준으로 미리 차감하고, 완료 후 실제 길이를 정수 초로 반올림해 정산합니다. 영상 편집에는 참조 영상이 있는 요청용 단가가 적용됩니다. 참조 영상이 있으면 과금 초 = 영상 길이 + max(참조 영상 총 길이, ⌈영상 길이 × 2/3⌉)이며, 참조 영상 총 길이는 제출 시 개별로 측정해 합산한 뒤 초 단위로 내림하고 이후에는 조정하지 않습니다. 초안에서 만든 최종본은 1080p로, 초안의 길이(초안이 -1이었다면 초안의 실제 길이)로 과금되며, 초안에 참조 영상이 있었다면 최종본에도 참조 영상 길이가 포함됩니다. 실제 차감액은 멤버십 등급이나 계정 그룹 할인에 따라 정해지니 이 페이지의 실시간 가격표를 확인하세요.

APIMart에서 두 모델 모두 POST /v1/videos/generations와 GET /v1/tasks/{task_id}를 사용하고, 21:9부터 9:16까지의 화면비로 4~30초 영상을 만들며, 요청당 참조 이미지 30장·영상 10개·오디오 10개까지 쓸 수 있고, seed, 오디오 생성, return_last_frame, output_format, 영상 편집(omni_reference_task_type: edit), 480p 초안 → 1080p 최종본 흐름을 지원합니다. 차이점은 다음과 같습니다. apimart-zoe(모델 ID apimart-zoe)는 2k·4k 출력도 지원하고, 첫·마지막 프레임과 참조 소재를 함께 쓸 수 없고, 참조 오디오를 보낼 때는 참조 이미지나 영상이 필요하며, audio를 생략하면 오디오 생성 여부를 모델이 정합니다. Seedance 2.5(seedance-2.5)는 generate_audio가 기본으로 켜져 있고 영상 연장(extend)도 지원하며, apimart-zoe의 extend는 아직 열리지 않았습니다. 참조 영상이 있으면 과금 초를 계산하는 방식도 다릅니다. 항목별 차이와 현재 초당 가격은 이 페이지의 비교표를 확인하세요.

해상도와 참조 영상 유무에 따라 다릅니다. 이 페이지의 가격 비교는 참조 영상 유무별로 두 모델의 현재 초당 단가, 차이(%), 자주 쓰는 길이의 비용 예시를 보여 줍니다. 참조 영상이 있으면 apimart-zoe는 출력 초에 max(참조 영상 총 초 내림값, ⌈출력 초 × 2/3⌉)를 더하고 Seedance 2.5는 참조 영상 초를 더하므로, 내 영상 길이에 맞는 예시로 비교하세요. apimart-zoe에는 Seedance 2.5에 없는 2k·4k 구간도 있습니다. 단가는 APIMart 가격 API에서 가져오며 멤버십 등급에 따라 다릅니다.

무료가 아닙니다. 출력 초 단위의 종량제이며, 초안과 그 최종본은 각각 한 번의 생성으로 과금됩니다. 제출 단계의 오류는 과금되지 않고, 잔액이 부족하면 402가 반환되며, 실패한 작업은 자동으로 환불되어 data.cost가 0으로 표시됩니다. 가격은 멤버십 등급이나 계정 그룹에 따라 다르며, 해상도별 현재 가격은 이 페이지의 실시간 가격표에 표시됩니다.

APIMart에 가입하고 대시보드의 API Keys 페이지에서 키를 만든 뒤 Authorization: Bearer <key>로 보내세요. 같은 키로 apimart-zoe API와 APIMart의 다른 모델을 호출할 수 있으며, 종량제로 구독이 필요 없습니다.