메인 콘텐츠로 건너뛰기
POST
/
v1
/
videos
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "happyhorse-1.0",
    "prompt": "길을 걷는 어린 소녀, 영화 같은 화면",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "happyhorse-1.0",
    "prompt": "길을 걷는 어린 소녀, 영화 같은 화면",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}

​
인증

​
Authorization
string
필수
모든 API 엔드포인트는 Bearer Token 인증이 필요합니다API 키 받기:API 키 관리 페이지에서 API 키를 받으세요요청 헤더에 추가:
Authorization: Bearer YOUR_API_KEY

​
모드 라우팅

happyhorse-1.0은 텍스트→동영상 / 이미지→동영상 / 참조 이미지→동영상 / 동영상 편집의 통합 엔드포인트입니다. 백엔드가 전달된 파라미터에 따라 모드를 자동 판단하며, 모든 모드는 동일한 규칙(해상도 × 초)으로 과금됩니다:
전달하는 필드라우팅 대상모드 설명
prompt만텍스트→동영상 (T2V)순수 텍스트로 동영상 생성
prompt + first_frame_image이미지→동영상 (I2V)이미지를 첫 프레임으로 동영상 생성
prompt + image_urls (1~9 장)참조 이미지→동영상 (R2V)일련의 참조 이미지로 새로운 장면 생성
prompt + video_url (선택적으로 image_urls 0~5 장 스타일 참조 / audio_setting)동영상 편집 (EDIT)원본 동영상 재작성/스타일 변환
라우팅 우선순위 (높음→낮음): video_url > first_frame_image > image_urls > prompt만. 필드 상호 배타 규칙: 세 개의 미디어 필드(first_frame_image / image_urls / video_url)는 쌍으로 상호 배타입니다. 유일한 유효 조합은 video_url + image_urls (EDIT 모드 + 참조 이미지)입니다. 상호 배타 필드를 동시에 전달하면 400 mixed_media_not_allowed를 반환합니다.

​
요청 매개변수

​
model
string
필수
동영상 생성 모델 이름. happyhorse-1.0로 고정
​
prompt
string
동영상 내용 설명, 최대 2500자. 특수 토큰을 포함할 수 없음
  • T2V / R2V / EDIT 모드: 필수
  • I2V 모드: 선택, 단 카메라 워크와 동작 지시를 위해 권장
예: "길을 걷는 어린 소녀, 영화 같은 화면"
​
first_frame_image
string
첫 프레임 이미지. I2V (이미지→동영상)를 트리거. URL 또는 base64(data:image/<mime>;base64,<payload>, 게이트웨이가 자동으로 OSS에 업로드) 지원image_urls / video_url과 상호 배타
첫 프레임 이미지 요구사항:
  • 형식: JPEG / JPG / PNG / BMP / WEBP
  • 짧은 변 픽셀: ≥ 300px
  • 가로세로 비율: 1:2.5 ~ 2.5:1
  • 파일 크기: ≤ 10MB
​
image_urls
array<string>
이미지 배열:
  • R2V 모드 (image_urls만 전달): 1~9 장, 피사체/스타일 참조로 새 장면 생성
  • EDIT 모드 (video_url과 함께 전달): 0~5 장, 스타일 참조 이미지로 사용
URL 또는 base64 지원first_frame_image와 상호 배타, video_url과는 함께 사용 가능
참조 이미지 요구사항:
  • 형식: JPEG / JPG / PNG / BMP / WEBP
  • 짧은 변 픽셀: ≥ 720p 권장
  • 가로세로 비율: 짧은 변/긴 변 ≥ 0.4
  • 파일 크기: ≤ 10MB
  • 개수: R2V는 반드시 1~9 장, EDIT는 최대 5 장
​
video_url
string
소스 동영상 URL. EDIT (동영상 편집)을 트리거. base64는 지원하지 않으며, HTTP/HTTPS 직접 링크를 제공해야 함first_frame_image와 상호 배타, image_urls (≤ 5 장)와는 함께 사용 가능
소스 동영상 요구사항:
  • 길이: 3~60 초 (> 15s인 경우 업스트림이 0초부터 15초까지 자동 자름)
  • 해상도: 최소 480p, 짧은 변 ≥ 360
  • 가로세로 비율: 1:8 ~ 8:1
  • 형식: MP4 / MOV (H.264 권장)
  • 프레임 레이트: > 8 fps
  • 파일 크기: ≤ 100MB
EDIT 모드에서는 생성된 동영상의 길이가 소스 동영상과 동일합니다 (소스가 15초를 초과하면 잘린 15초 기준). 이때 duration 파라미터는 적용되지 않습니다. 출력 길이를 제어하려면 업로드 전에 소스 동영상을 원하는 길이로 잘라주세요.
​
audio_setting
string
기본값:"auto"
오디오 설정. EDIT 모드에서만 유효 (video_url 전달 필수)옵션:
  • auto - 자동 생성 오디오 (기본값)
  • origin - 원본 동영상 오디오 트랙 유지
EDIT 모드 외에서 본 필드를 전달하면 400 audio_setting_only_for_edit를 반환합니다
​
resolution
string
기본값:"1080P"
동영상 해상도 (과금에 영향)옵션:
  • 720P - 표준
  • 1080P - 고화질 (기본값)
​
duration
integer
기본값:"5"
동영상 길이 (초, 과금에 영향)지원 범위: 3 ~ 15의 임의의 정수기본값: 5
EDIT 모드 (video_url 전달 시) 에서는 본 파라미터가 적용되지 않습니다: 생성된 동영상의 길이는 소스 동영상과 동일하게 유지됩니다 (소스가 15초를 초과하면 잘린 15초 기준으로 과금). 출력 길이를 제어하려면 사전에 소스 동영상을 잘라주세요.
​
size
string
기본값:"16:9"
화면 비율지원 형식:
  • 16:9 - 가로 와이드 (기본값)
  • 9:16 - 세로
  • 1:1 - 정사각형
  • 4:3 - 가로
  • 3:4 - 세로
I2V / EDIT 모드에서는 무시됩니다 — 출력 비율은 입력 미디어(첫 프레임 이미지 / 소스 동영상)에 따라 자동 결정됩니다
​
watermark
boolean
기본값:"true"
생성된 동영상에 워터마크 추가 여부
  • true: 워터마크 추가 (기본값)
  • false: 추가 안 함
​
seed
integer
생성 내용의 무작위성을 제어하는 시드범위: [0, 2147483647]. 생략 시 무작위
  • 동일한 요청에서 다른 seed 값을 받으면 (예: seed를 지정하지 않음) 다른 결과가 생성됩니다
  • 동일한 요청에서 동일한 seed 값을 받으면 유사한 결과가 생성되지만 완전한 일치는 보장되지 않습니다

​
응답

​
code
integer
응답 상태 코드. 성공 시 200
​
data
array
응답 데이터 배열

​
사용 사례

​
사례 1: 텍스트→동영상 T2V (최소 요청)

{
  "model": "happyhorse-1.0",
  "prompt": "길을 걷는 어린 소녀, 영화 같은 화면"
}

​
사례 2: 텍스트→동영상 T2V (전체 매개변수)

{
  "model": "happyhorse-1.0",
  "prompt": "석양이 비치는 해변 도로, 슬로우 모션 카메라 푸시 인, 영화 같은 화면",
  "resolution": "1080P",
  "size": "16:9",
  "duration": 8,
  "watermark": false,
  "seed": 42
}

​
사례 3: 이미지→동영상 I2V (first_frame_image)

{
  "model": "happyhorse-1.0",
  "prompt": "이미지의 장면을 움직이게 해주세요",
  "first_frame_image": "https://example.com/first_frame.png",
  "resolution": "1080P",
  "duration": 5
}

​
사례 4: 참조 이미지→동영상 R2V (다중 참조 이미지)

{
  "model": "happyhorse-1.0",
  "prompt": "이미지1의 주인공이 이미지2의 장면을 달리고, 그 후 이미지3의 도구를 집어든다. 3D 카툰 스타일을 유지하고 동작은 부드럽게.",
  "image_urls": [
    "https://example.com/img_01.jpg",
    "https://example.com/img_02.png",
    "https://example.com/img_03.jpeg"
  ],
  "resolution": "1080P",
  "size": "16:9",
  "duration": 5,
  "watermark": false
}

​
사례 5: 동영상 편집 EDIT (원본 오디오 유지 + 스타일 참조)

{
  "model": "happyhorse-1.0",
  "prompt": "동영상의 캐릭터를 카툰 스타일로 변환하되, 원본 동작을 유지",
  "video_url": "https://example.com/source.mp4",
  "image_urls": [
    "https://example.com/style_ref.jpg"
  ],
  "resolution": "1080P",
  "audio_setting": "origin",
  "seed": 42
}

​
사례 6: 720P로 요금 절약

{
  "model": "happyhorse-1.0",
  "prompt": "석양에 모래사장에 부딪히는 파도",
  "resolution": "720P",
  "size": "16:9",
  "duration": 5
}

​
모드 선택 가이드

요구 사항권장 방법
순수 텍스트로 동영상 생성prompt만 전달 (T2V)
이미지를 “움직이게” 하기 (첫 프레임으로 사용)first_frame_image 전달 (I2V)
일련의 참조 이미지로 새 장면 생성image_urls (1~9 장, R2V) 전달
기존 동영상 재작성/스타일 변환video_url (EDIT) 전달, image_urls 0~5 장을 스타일 참조로 함께 사용 가능
요금 절약resolution: "720P" 지정

​
사용 팁

  1. 통합 엔드포인트 동작: 전달된 필드로 모드가 결정됩니다. 세 개의 미디어 필드(first_frame_image / image_urls / video_url)는 쌍으로 상호 배타입니다
  2. size는 T2V/R2V에서만 유효: I2V / EDIT 모드에서는 size가 무시되며, 출력 비율은 입력 미디어에 따라 결정됩니다
  3. 길이: 5~10초가 최적입니다. 너무 짧으면 동작이 끊기고, 너무 길면 업스트림 처리 시간이 크게 증가합니다
  4. 첫 프레임 이미지 품질: 선명, 구도 명확, 피사체 중앙 — I2V 효과를 크게 향상시킵니다
  5. 프롬프트 작성: 움직임 / 카메라 워크 / 분위기를 묘사 (예: “천천히 푸시 인, 영화 같은, 따뜻한 톤”)하면 정적인 장면 묘사보다 좋은 결과를 얻습니다
  6. EDIT 입력 동영상: > 15초인 경우 업스트림이 0초부터 15초까지 자동으로 자릅니다. 다른 세그먼트가 필요하면 동영상을 미리 분할하세요
작업 결과 조회동영상 생성은 비동기 작업으로, 제출 후 task_id가 반환됩니다. 작업 상태 조회 엔드포인트를 사용하여 생성 진행 상황과 결과를 조회하세요.