메인 콘텐츠로 건너뛰기
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": "wan2.7-r2v",
    "prompt": "이 사람이 차가 붐비는 거리를 걸어간다",
    "image_with_roles": [{"url": "https://cdn.example.com/character.jpg", "role": "reference_image"}],
    "resolution": "1080P",
    "duration": 8
  }'

{
  "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": "wan2.7-r2v",
    "prompt": "이 사람이 차가 붐비는 거리를 걸어간다",
    "image_with_roles": [{"url": "https://cdn.example.com/character.jpg", "role": "reference_image"}],
    "resolution": "1080P",
    "duration": 8
  }'

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

​
인증

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

​
요청 매개변수

​
model
string
필수
동영상 생성 모델 이름. wan2.7-r2v로 고정
​
prompt
string
필수
동영상 내용 설명, 최대 5000자여러 이미지/동영상의 경우 “이미지1”, “이미지2”, “동영상1” 등의 번호로 참조 소재를 지정 (입력 순서대로)예: "이미지1의 인물이 이미지2의 장면으로 들어와 주위를 둘러본다"
​
image_with_roles
array<object>
역할이 지정된 이미지 배열. video_urls와 최소 하나는 전달 필요각 객체 필드:
  • url (string): 이미지 URL
  • role (string): 이미지 역할
    • reference_image - 참조 이미지 (기본값)
    • first_frame - 첫 프레임 지정 (전달 시 size 매개변수는 무효, 첫 프레임 이미지의 비율 적용)
  • reference_voice (string, 선택): 해당 참조 캐릭터의 음성 샘플 오디오 URL. 생성된 동영상 내 캐릭터 목소리 제어에 사용
예:
[
  {
    "url": "https://cdn.example.com/character.jpg",
    "role": "reference_image",
    "reference_voice": "https://cdn.example.com/voice_sample.mp3"
  },
  { "url": "https://cdn.example.com/start.jpg", "role": "first_frame" }
]
​
video_urls
array<string>
참조 동영상 URL 배열, 최대 5개 (이미지+동영상 총합 ≤ 5)image_with_roles와 최소 하나는 전달 필요
동영상 제한:
  • 형식: mp4, mov
  • 길이: 1~30초
  • 해상도: 너비와 높이 모두 [240, 4096] 픽셀 범위
  • 가로세로 비율: 1:8 ~ 8:1
  • 파일 크기: 100MB 이하
​
negative_prompt
string
원하지 않는 내용을 설명하는 네거티브 프롬프트, 최대 500자
​
resolution
string
기본값:"1080P"
동영상 해상도옵션:
  • 720P - 표준
  • 1080P - 고화질 (기본값)
​
duration
integer
기본값:"5"
동영상 길이 (초)지원 범위: 2 ~ 15초기본값: 5
참조 소재에 동영상이 포함된 경우: [2, 10] 범위의 정수참조 소재에 동영상이 포함되지 않은 경우: [2, 15] 범위의 정수
​
size
string
기본값:"16:9"
화면 비율지원 형식:
  • 16:9 - 가로 와이드 (기본값)
  • 9:16 - 세로
  • 1:1 - 정사각형
  • 4:3 - 가로
  • 3:4 - 세로
image_with_roles를 통해 first_frame이 전달되면 이 매개변수는 무시되며, 비율은 첫 프레임 이미지 기준으로 설정됩니다
​
prompt_extend
boolean
기본값:"true"
프롬프트 지능 재작성 활성화 여부짧은 프롬프트에서 효과가 크지만 처리 시간이 증가합니다기본값: true
​
watermark
boolean
기본값:"false"
생성된 동영상에 “AI 생성” 워터마크 추가 여부
  • true: 워터마크 추가
  • false: 추가 안 함 (기본값)
​
seed
integer
생성 내용의 무작위성을 제어하는 시드 정수범위: ≥0의 정수
  • 동일한 요청에서 다른 seed 값을 받으면 (예: seed를 지정하지 않음) 다른 결과가 생성됩니다
  • 동일한 요청에서 동일한 seed 값을 받으면 유사한 결과가 생성되지만 완전한 일치는 보장되지 않습니다

​
응답

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

​
사용 사례

​
사례 1: 단일 참조 이미지 생성 (최소)

{
  "model": "wan2.7-r2v",
  "prompt": "이 사람이 차가 붐비는 거리를 걸어간다",
  "image_with_roles": [
    { "url": "https://cdn.example.com/character.jpg", "role": "reference_image" }
  ]
}

​
사례 2: 다중 참조 이미지 생성

{
  "model": "wan2.7-r2v",
  "prompt": "이미지1의 인물이 이미지2의 장면으로 들어와 이미지3의 동작을 따라한다",
  "image_with_roles": [
    { "url": "https://cdn.example.com/person.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/background.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/pose.jpg", "role": "reference_image" }
  ],
  "resolution": "1080P",
  "duration": 8,
  "size": "16:9"
}

​
사례 3: 참조 동영상 기반 생성

{
  "model": "wan2.7-r2v",
  "prompt": "참조 동영상의 스타일로 해변 일몰 장면을 생성",
  "video_urls": ["https://cdn.example.com/style_reference.mp4"],
  "resolution": "720P",
  "duration": 8
}

​
사례 4: 첫 프레임 지정 + 참조 이미지

{
  "model": "wan2.7-r2v",
  "prompt": "참조 인물이 이 위치에서 앞으로 걸어나간다",
  "image_with_roles": [
    { "url": "https://cdn.example.com/character.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/start.jpg", "role": "first_frame" }
  ],
  "resolution": "1080P",
  "duration": 8
}

​
사례 5: 참조 이미지 + 참조 음성 (정밀한 방법)

{
  "model": "wan2.7-r2v",
  "prompt": "이 사람이 거리를 걸으면서 말한다",
  "image_with_roles": [
    {
      "url": "https://cdn.example.com/character.jpg",
      "role": "reference_image",
      "reference_voice": "https://cdn.example.com/voice_sample.mp3"
    }
  ],
  "resolution": "1080P",
  "duration": 10
}

​
이미지 참조 규칙

여러 참조 이미지가 있는 경우 prompt 내에서 번호로 참조합니다:
  • 1번째 이미지 → “이미지1” 또는 “첫 번째 이미지”
  • 1번째 동영상 → “동영상1” 또는 “첫 번째 동영상”
작업 결과 조회동영상 생성은 비동기 작업으로, 제출 후 task_id가 반환됩니다. 작업 상태 조회 엔드포인트를 사용하여 생성 진행 상황과 결과를 조회하세요.