메인 콘텐츠로 건너뛰기
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.1",
    "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.1",
    "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.1은 텍스트→동영상 / 이미지→동영상 / 참조 이미지→동영상의 통합 엔드포인트입니다. 백엔드가 전달된 파라미터에 따라 모드를 자동 판단하며, 모든 모드는 동일한 규칙(해상도 × 초)으로 과금됩니다:
전달하는 필드라우팅 대상모드 설명
prompt만텍스트→동영상 (T2V)순수 텍스트로 동영상 생성
prompt + first_frame_image이미지→동영상 (I2V)이미지를 첫 프레임으로 동영상 생성
prompt + image_urls (1~9 장)참조 이미지→동영상 (R2V)일련의 참조 이미지로 새로운 장면 생성
라우팅 우선순위 (높음→낮음): first_frame_image > image_urls > prompt만. 필드 상호 배타 규칙: 두 개의 미디어 필드(first_frame_image / image_urls)는 상호 배타입니다. 상호 배타 필드를 동시에 전달하면 400 mixed_media_not_allowed를 반환합니다.

​
요청 매개변수

​
model
string
필수
동영상 생성 모델 이름. happyhorse-1.1로 고정
​
prompt
string
동영상 내용 설명, 최대 2500자. 특수 토큰을 포함할 수 없음예: "길을 걷는 어린 소녀, 영화 같은 화면"
​
first_frame_image
string
첫 프레임 이미지. I2V (이미지→동영상)를 트리거. URL 또는 base64(data:image/<mime>;base64,<payload>, 게이트웨이가 자동으로 OSS에 업로드) 지원image_urls와 상호 배타
첫 프레임 이미지 요구사항:
  • 형식: JPEG / JPG / PNG / BMP / WEBP
  • 짧은 변 픽셀: ≥ 300px
  • 가로세로 비율: 1:2.5 ~ 2.5:1
  • 파일 크기: ≤ 10MB
​
image_urls
array<string>
이미지 배열 (R2V 모드): 1~9 장, 피사체/스타일 참조로 새 장면 생성URL 또는 base64 지원first_frame_image와 상호 배타
참조 이미지 요구사항:
  • 형식: JPEG / JPG / PNG / BMP / WEBP
  • 짧은 변 픽셀: ≥ 720p 권장
  • 가로세로 비율: 짧은 변/긴 변 ≥ 0.4
  • 파일 크기: ≤ 10MB
  • 개수: 1~9 장
​
resolution
string
기본값:"1080P"
동영상 해상도 (과금에 영향)옵션:
  • 720P - 표준
  • 1080P - 고화질 (기본값)
​
duration
integer
기본값:"5"
동영상 길이 (초, 과금에 영향)지원 범위: 3 ~ 15의 임의의 정수기본값: 5
​
size
string
기본값:"16:9"
화면 비율지원 형식:
  • 16:9 - 가로 와이드 (기본값)
  • 9:16 - 세로
  • 1:1 - 정사각형
  • 4:3 - 가로
  • 3:4 - 세로
I2V 모드에서는 무시됩니다 — 출력 비율은 입력 미디어(첫 프레임 이미지)에 따라 자동 결정됩니다
​
watermark
boolean
기본값:"false"
생성된 동영상에 워터마크를 추가할지 여부
  • true: 워터마크 추가
  • false: 워터마크 미추가 (기본값)
​
seed
integer
생성 내용의 무작위성을 제어하는 시드범위: [0, 2147483647]. 생략 시 무작위
  • 동일한 요청에서 다른 seed 값을 받으면 (예: seed를 지정하지 않음) 다른 결과가 생성됩니다
  • 동일한 요청에서 동일한 seed 값을 받으면 유사한 결과가 생성되지만 완전한 일치는 보장되지 않습니다

​
응답

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

​
사용 사례

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

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

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

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

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

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

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

{
  "model": "happyhorse-1.1",
  "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
}

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

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

​
모드 선택 가이드

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

​
사용 팁

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