메인 콘텐츠로 건너뛰기
POST
/
v1
/
videos
/
generations
curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "wan2.7-reference-video",
  "prompt": "참조 동영상의 인물이 풀밭에서 춤춘다",
  "video_urls": [
    "https://example.com/reference.mp4"
  ]
}
'
{
  "created": 1757169743,
  "id": "task-unified-1757169743-7cvnl5zw",
  "model": "wan2.7-reference-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 120
  },
  "type": "video",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 5,
    "user_group": "default"
  }
}

인증

​
Authorization
string
header
필수

모든 API는 Bearer Token 인증이 필요합니다

API Key 받기:

API Key 관리 페이지에서 API Key를 받으세요

요청 헤더에 추가:

Authorization: Bearer YOUR_API_KEY

본문

application/json
​
model
enum<string>
필수

모델명, wan2.7-reference-video 고정

사용 가능한 옵션:
wan2.7-reference-video
예시:

"wan2.7-reference-video"

​
prompt
string
필수

동영상 생성용 텍스트 프롬프트. 중국어와 영어 지원, 각 글자 / 문자 / 문장부호를 1자로 카운트하며 초과분은 자동으로 잘립니다. 최대 5000자

캐릭터 인덱싱 규칙:

  • 중국어: "图1, 图2 / 视频1, 视频2" 사용 — image_urls / video_urls 배열 순서에 1-based로 대응
  • 영어: "Image 1", "Video 1" 사용(첫 글자 대문자, 단어와 숫자 사이 공백)
  • 이미지와 동영상은 별도로 카운트되어 "Image 1"과 "Video 1"이 공존 가능
  • 참조 이미지나 참조 동영상이 1개뿐인 경우 "the reference image"나 "the reference video"로 간단히 표기 가능

다중 그리드 이미지(스토리보드): 다중 그리드 이미지 1장을 전달하는 경우, 프롬프트는 다중 분할 형식으로 핵심 화면을 기술. 모델이 그리드 레이아웃을 인식하고 전환을 자동 보완합니다

Maximum string length: 5000
예시:

"Video 1이 Image 3을 안고 Image 4의 의자에서 부드러운 컨트리 포크를 연주함"

​
negative_prompt
string

동영상에 나타나지 않기를 원하는 내용을 기술하는 네거티브 프롬프트. 중국어와 영어 지원, 최대 500자, 초과분은 자동으로 잘립니다

Maximum string length: 500
예시:

"흐림, 저품질"

​
image_start
string<uri>

시작 프레임 이미지 URL. 동영상의 시작 화면으로 사용. image_urls + video_urls ≤ 5의 참조 미디어 상한에 카운트되지 않음. 보이스 바인딩을 받지 않음(시작 프레임 자체는 다중 캐릭터 보이스 할당에 참여하지 않음)

활용 시나리오:

  • 시작 프레임에 참조 대상이 이미 등장: 참조 소재와 결합하여 주체 일관성 강화
  • 시작 프레임에 참조 대상이 없음: 참조 소재로 동영상 진행 중 등장하는 새 주체 정의

이미지 제한:

  • 포맷: JPEG, JPG, PNG(투명도 미지원), BMP, WEBP
  • 해상도: 가로/세로가 [240, 8000] 픽셀
  • 종횡비: 1:8 ~ 8:1
  • 파일 크기: 20MB 이하
예시:

"https://example.com/first_frame.jpg"

​
image_urls
string<uri>[]

참조 이미지 URL 배열. 주체 캐릭터(인물/동물/사물) 또는 장면 배경 제공 가능. 주체 포함 시 각 이미지에 단일 캐릭터만 포함 권장

수량 제한:

  • image_urls + video_urls 합계 ≤ 5
  • video_urls와 함께 둘 중 하나 이상 필수(image_start만으로는 요건을 충족하지 않음)

이미지 제한:

  • 포맷: JPEG, JPG, PNG(투명도 미지원), BMP, WEBP
  • 해상도: 가로/세로가 [240, 8000] 픽셀
  • 종횡비: 1:8 ~ 8:1
  • 파일 크기: 20MB 이하
예시:
[
  "https://example.com/ref1.jpg",
  "https://example.com/ref2.jpg"
]
​
video_urls
string<uri>[]

참조 동영상 URL 배열. 동영상 내용에는 주체(인물/동물/사물) 포함을 권장하며, 빈 샷이나 순수 배경 동영상은 비권장. 주체 포함 시 각 동영상에 단일 캐릭터만 포함 권장. 동영상에 음성이 있으면 보이스 참조로 활용 가능

수량 제한:

  • image_urls + video_urls 합계 ≤ 5
  • image_urls와 함께 둘 중 하나 이상 필수

동영상 제한:

  • 포맷: mp4, mov
  • 길이: 1 ~ 30초
  • 해상도: 가로/세로가 [240, 4096] 픽셀
  • 종횡비: 1:8 ~ 8:1
  • 파일 크기: 100MB 이하

참고: 요청에 video_urls를 전달하면 duration 상한이 10초로 제한됩니다

예시:
["https://example.com/reference.mp4"]
​
audio_urls
string<uri>[]

[호환성 필드 — model_params.voice_bindings 사용 권장]

참조 보이스 음성 URL 배열. 참조 소재에 위치 순서대로 바인딩됩니다 — 먼저 video_urls 배열, 그다음 image_urls 배열의 순으로 출현 순서에 1대1 정렬. 최대 5개 요소

우선순위:

  • model_params.voice_bindings와 audio_urls를 동시에 전달한 경우 voice_bindings만 사용되며 본 필드는 무시됩니다
  • video_urls의 동영상에 음성이 있고 보이스 바인딩이 미지정인 경우 원본 음성을 사용합니다. 명시적 보이스 바인딩 지정 시 원본을 덮어씁니다

음성 제한:

  • 지원 포맷: wav, mp3
  • 길이: 1 ~ 10초
  • 파일 크기: 15MB 이하
Maximum array length: 5
예시:
[
  "https://example.com/voice1.mp3",
  "https://example.com/voice2.mp3"
]
​
model_params
object

고급 파라미터 컨테이너(권장)

​
quality
enum<string>
기본값:720p

동영상 품질, 기본값 720p

옵션:

  • 720p: 표준 화질, 표준 가격(기본)
  • 1080p: 고화질, 가격 상승
사용 가능한 옵션:
720p,
1080p
예시:

"720p"

​
aspect_ratio
enum<string>
기본값:16:9

동영상 종횡비, 기본값 16:9

동작:

  • image_start 미전달: 지정한 aspect_ratio로 동영상 생성
  • image_start 전달: 본 필드는 무시되며, 시작 프레임 이미지의 종횡비에 가까운 비율로 생성

품질 등급별 출력 해상도:

품질16:99:161:14:33:4
720p1280×720720×1280960×9601104×832832×1104
1080p1920×10801080×19201440×14401648×12481248×1648
사용 가능한 옵션:
16:9,
9:16,
1:1,
4:3,
3:4
예시:

"16:9"

​
duration
number
기본값:5

동영상 길이(초, 정수)

범위:

  • video_urls 미전달: 2 ~ 15, 기본값 5
  • video_urls 전달: 2 ~ 10(10초로 제한)

청구: 실제 생성된 동영상 길이 기준

필수 범위: 2 <= x <= 15
예시:

5

​
seed
integer

랜덤 시드, 기본값은 랜덤

설명:

  • 범위: 1 ~ 2147483647
  • 시드를 고정하면 프롬프트 반복 시 변동을 줄이고 재현성을 높입니다
필수 범위: 1 <= x <= 2147483647
예시:

42

​
prompt_extend
boolean
기본값:false

프롬프트 지능 재작성 활성화 여부. 활성화 시 대형 모델이 프롬프트를 최적화하여 단순하거나 설명이 부족한 프롬프트의 결과를 크게 개선합니다.

참고: 기본값은 false입니다. 필드를 생략하거나 false를 보내면 재작성이 발생하지 않습니다. 활성화하려면 명시적으로 true를 보내세요.

예시:

false

​
callback_url
string<uri>

작업 완료 시의 HTTPS 콜백 URL

콜백 시점:

  • 작업 완료(completed), 실패(failed), 취소(cancelled) 시 트리거
  • 청구 확정 후 전송

보안 제약:

  • HTTPS만 지원
  • 내부 IP 주소(127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x 등)로의 콜백 금지
  • URL 길이는 2048자 이하

콜백 메커니즘:

  • 타임아웃: 10초
  • 실패 시 최대 3회 재시도(실패 후 1/2/4초 시점)
  • 콜백 응답 형식은 작업 조회 API와 동일
  • 2xx 상태 코드는 성공으로 간주, 그 외는 재시도 트리거
예시:

"https://your-domain.com/webhooks/video-task-completed"

응답

동영상 작업 생성 성공

​
created
integer

작업 생성 타임스탬프

예시:

1757169743

​
id
string

작업 ID

예시:

"task-unified-1757169743-7cvnl5zw"

​
model
string

실제로 사용한 모델명

예시:

"wan2.7-reference-video"

​
object
enum<string>

작업의 구체적인 종류

사용 가능한 옵션:
video.generation.task
​
progress
integer

작업 진행률 (0-100)

필수 범위: 0 <= x <= 100
예시:

0

​
status
enum<string>

작업 상태

사용 가능한 옵션:
pending,
processing,
completed,
failed
예시:

"pending"

​
task_info
object

동영상 작업 상세 정보

​
type
enum<string>

작업 출력 유형

사용 가능한 옵션:
text,
image,
audio,
video
예시:

"video"

​
usage
object

사용량 및 청구 정보