> ## Documentation Index > Fetch the complete documentation index at: https://docs.evolink.ai/llms.txt > Use this file to discover all available pages before exploring further. # Wan2.7 참조 비디오 > - WAN2.7 (wan2.7-reference-video) 모델은 참조→동영상 생성을 지원하며, 사람이나 사물을 주인공으로 단일 캐릭터 연기 또는 다중 캐릭터 인터랙션 동영상을 생성할 수 있습니다 - 멀티모달 입력: 시작 프레임 이미지(`image_start`), 다수의 참조 이미지(`image_urls`), 다수의 참조 동영상(`video_urls`), 캐릭터별 보이스 바인딩 - **최소 1개**의 참조 이미지(`image_urls`) 또는 참조 동영상(`video_urls`)이 필요합니다. `image_start`만으로는 요건을 충족하지 않습니다. `image_urls` + `video_urls` 합계 ≤ 5 - **프롬프트 내 캐릭터 인덱싱:** 중국어는 "图1, 图2 / 视频1, 视频2", 영어는 "Image 1", "Video 1" 사용 — `image_urls` / `video_urls` 배열 순서에 1-based로 대응. 이미지와 동영상은 별도로 카운트되어 "Image 1"과 "Video 1"이 공존 가능 - **다중 캐릭터 보이스 바인딩:** `model_params.voice_bindings`(정밀 바인딩) 사용 권장. 레거시 필드 `audio_urls`(위치 정렬)도 지원 - 비동기 처리 모드, 반환된 작업 ID로 [상태 조회](/ko/api-manual/task-management/get-task-detail) - 생성된 동영상 링크는 24시간 유효합니다. 가능한 한 빨리 저장하세요 - **청구:** "입력 동영상 길이 + 출력 동영상 길이" 기준으로 청구. 생성 성공 시에만 청구되며 실패는 무료 ## OpenAPI ````yaml ko/api-manual/video-series/wan2.7/wan2.7-reference-video.json POST /v1/videos/generations openapi: 3.1.0 info: title: wan2.7-reference-video API description: WAN2.7 모델로 참조 이미지, 참조 동영상 및 오디오 입력을 결합하여 동영상을 생성합니다 license: name: MIT version: 1.0.0 servers: - url: https://api.evolink.ai description: 프로덕션 환경 security: - bearerAuth: [] paths: /v1/videos/generations: post: tags: - 동영상 생성 summary: wan2.7-reference-video API description: >- - WAN2.7 (wan2.7-reference-video) 모델은 참조→동영상 생성을 지원하며, 사람이나 사물을 주인공으로 단일 캐릭터 연기 또는 다중 캐릭터 인터랙션 동영상을 생성할 수 있습니다 - 멀티모달 입력: 시작 프레임 이미지(`image_start`), 다수의 참조 이미지(`image_urls`), 다수의 참조 동영상(`video_urls`), 캐릭터별 보이스 바인딩 - **최소 1개**의 참조 이미지(`image_urls`) 또는 참조 동영상(`video_urls`)이 필요합니다. `image_start`만으로는 요건을 충족하지 않습니다. `image_urls` + `video_urls` 합계 ≤ 5 - **프롬프트 내 캐릭터 인덱싱:** 중국어는 "图1, 图2 / 视频1, 视频2", 영어는 "Image 1", "Video 1" 사용 — `image_urls` / `video_urls` 배열 순서에 1-based로 대응. 이미지와 동영상은 별도로 카운트되어 "Image 1"과 "Video 1"이 공존 가능 - **다중 캐릭터 보이스 바인딩:** `model_params.voice_bindings`(정밀 바인딩) 사용 권장. 레거시 필드 `audio_urls`(위치 정렬)도 지원 - 비동기 처리 모드, 반환된 작업 ID로 [상태 조회](/ko/api-manual/task-management/get-task-detail) - 생성된 동영상 링크는 24시간 유효합니다. 가능한 한 빨리 저장하세요 - **청구:** "입력 동영상 길이 + 출력 동영상 길이" 기준으로 청구. 생성 성공 시에만 청구되며 실패는 무료 operationId: createWan27ReferenceVideoGeneration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Wan27ReferenceVideoRequest' examples: single_reference_video: summary: 단일 참조 동영상 value: model: wan2.7-reference-video prompt: 참조 동영상의 인물이 풀밭에서 춤춘다 video_urls: - https://example.com/reference.mp4 multi_subject_with_voice_bindings: summary: 다중 주체 참조 + 정밀 보이스 바인딩(권장) value: model: wan2.7-reference-video prompt: >- Image 1이 Image 2를 안고 Image 3의 의자에서 부드러운 컨트리 포크를 연주하며 "오늘 햇빛이 정말 좋네요"라고 말함 image_urls: - https://example.com/girl.jpg - https://example.com/object.png - https://example.com/chair.png model_params: voice_bindings: image1: https://example.com/girl_voice.mp3 duration: 10 multi_grid_storyboard: summary: 단일 참조 이미지(다중 그리드 스토리보드) value: model: wan2.7-reference-video prompt: >- 참조 이미지, 3D 카툰 어드벤처 영화 스타일. 스토리보드: 1. 판타지 숲의 와이드 샷; 2. 소년이 덩굴을 헤치고 정찰; 3. 작은 로봇이 앞쪽을 스캔; 4. 보물지도 클로즈업; 5. 흥분한 소년의 표정; 6. 뿌리를 뛰어넘으며 더 깊이 진입 image_urls: - https://example.com/storyboard.png duration: 10 responses: '200': description: 동영상 작업 생성 성공 content: application/json: schema: $ref: '#/components/schemas/VideoGenerationResponse' '400': description: 요청 파라미터 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: Invalid request parameters type: invalid_request_error '401': description: 인증되지 않음, 토큰이 유효하지 않거나 만료됨 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Invalid or expired token type: authentication_error '402': description: 할당량 부족, 충전 필요 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_quota message: Insufficient quota. Please top up your account. type: insufficient_quota '403': description: 접근 권한 없음 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: model_access_denied message: 'Token does not have access to model: wan2.7-reference-video' type: invalid_request_error '429': description: 요청 빈도 한도 초과 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Too many requests, please try again later type: rate_limit_error '500': description: 서버 내부 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: Internal server error type: api_error components: schemas: Wan27ReferenceVideoRequest: required: - model - prompt type: object properties: model: type: string description: 모델명, `wan2.7-reference-video` 고정 enum: - wan2.7-reference-video example: wan2.7-reference-video prompt: type: string description: >- 동영상 생성용 텍스트 프롬프트. 중국어와 영어 지원, 각 글자 / 문자 / 문장부호를 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장을 전달하는 경우, 프롬프트는 다중 분할 형식으로 핵심 화면을 기술. 모델이 그리드 레이아웃을 인식하고 전환을 자동 보완합니다 maxLength: 5000 example: Video 1이 Image 3을 안고 Image 4의 의자에서 부드러운 컨트리 포크를 연주함 negative_prompt: type: string description: >- 동영상에 나타나지 않기를 원하는 내용을 기술하는 네거티브 프롬프트. 중국어와 영어 지원, 최대 500자, 초과분은 자동으로 잘립니다 maxLength: 500 example: 흐림, 저품질 image_start: type: string format: uri description: >- 시작 프레임 이미지 URL. 동영상의 시작 화면으로 사용. **`image_urls` + `video_urls` ≤ 5의 참조 미디어 상한에 카운트되지 않음**. **보이스 바인딩을 받지 않음**(시작 프레임 자체는 다중 캐릭터 보이스 할당에 참여하지 않음) **활용 시나리오:** - 시작 프레임에 참조 대상이 이미 등장: 참조 소재와 결합하여 주체 일관성 강화 - 시작 프레임에 참조 대상이 없음: 참조 소재로 동영상 진행 중 등장하는 새 주체 정의 **이미지 제한:** - 포맷: JPEG, JPG, PNG(투명도 미지원), BMP, WEBP - 해상도: 가로/세로가 `[240, 8000]` 픽셀 - 종횡비: 1:8 ~ 8:1 - 파일 크기: `20MB` 이하 example: https://example.com/first_frame.jpg image_urls: type: array items: type: string format: uri description: >- 참조 이미지 URL 배열. 주체 캐릭터(인물/동물/사물) 또는 장면 배경 제공 가능. 주체 포함 시 각 이미지에 **단일** 캐릭터만 포함 권장 **수량 제한:** - `image_urls` + `video_urls` 합계 ≤ 5 - `video_urls`와 함께 둘 중 하나 이상 필수(`image_start`만으로는 요건을 충족하지 않음) **이미지 제한:** - 포맷: JPEG, JPG, PNG(투명도 미지원), BMP, WEBP - 해상도: 가로/세로가 `[240, 8000]` 픽셀 - 종횡비: 1:8 ~ 8:1 - 파일 크기: `20MB` 이하 example: - https://example.com/ref1.jpg - https://example.com/ref2.jpg video_urls: type: array items: type: string format: uri description: >- 참조 동영상 URL 배열. 동영상 내용에는 주체(인물/동물/사물) 포함을 권장하며, 빈 샷이나 순수 배경 동영상은 비권장. 주체 포함 시 각 동영상에 **단일** 캐릭터만 포함 권장. 동영상에 음성이 있으면 보이스 참조로 활용 가능 **수량 제한:** - `image_urls` + `video_urls` 합계 ≤ 5 - `image_urls`와 함께 둘 중 하나 이상 필수 **동영상 제한:** - 포맷: mp4, mov - 길이: `1 ~ 30`초 - 해상도: 가로/세로가 `[240, 4096]` 픽셀 - 종횡비: 1:8 ~ 8:1 - 파일 크기: `100MB` 이하 **참고:** 요청에 `video_urls`를 전달하면 `duration` 상한이 10초로 제한됩니다 example: - https://example.com/reference.mp4 audio_urls: type: array items: type: string format: uri maxItems: 5 description: >- **[호환성 필드 — `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` 이하 example: - https://example.com/voice1.mp3 - https://example.com/voice2.mp3 model_params: type: object description: 고급 파라미터 컨테이너(권장) properties: voice_bindings: type: object description: >- **다중 캐릭터 정밀 보이스 바인딩(권장).** `audio_urls`보다 우선 **바인딩 규칙:** - 키는 `image{N}` 또는 `video{N}` 형식(1-based, 선행 0 불가, 예: `image1`, `video2`) - 키의 N은 프롬프트의 "图N / Image N" 또는 "视频N / Video N"에 대응하며, `image_urls[N-1]` / `video_urls[N-1]`과 일치 - 각 값은 해당 캐릭터의 보이스 음성 URL - 총 바인딩 수 ≤ 5 - `image_start`(시작 프레임 이미지)는 보이스 바인딩을 **받지 않음** - 일부 캐릭터는 건너뛸 수 있음(예: image1과 image3만 바인딩, image2는 미바인딩) **음성 제한:** - 지원 포맷: `wav`, `mp3` - 길이: `1 ~ 10`초 - 파일 크기: `15MB` 이하 **검증 오류:** - 키 형식 오류: `voice_bindings key "img1"/"image01" invalid` - 인덱스 범위 초과: `voice_bindings.image5 out of range` - 빈 값, 중복 바인딩, 또는 5개 초과 additionalProperties: type: string format: uri example: image1: https://example.com/voice_a.mp3 image3: https://example.com/voice_c.mp3 video1: https://example.com/voice_v.mp3 quality: type: string description: |- 동영상 품질, 기본값 `720p` **옵션:** - `720p`: 표준 화질, 표준 가격(기본) - `1080p`: 고화질, 가격 상승 enum: - 720p - 1080p default: 720p example: 720p aspect_ratio: type: string description: >- 동영상 종횡비, 기본값 `16:9` **동작:** - `image_start` 미전달: 지정한 `aspect_ratio`로 동영상 생성 - `image_start` 전달: 본 필드는 **무시**되며, 시작 프레임 이미지의 종횡비에 가까운 비율로 생성 **품질 등급별 출력 해상도:** | 품질 | 16:9 | 9:16 | 1:1 | 4:3 | 3:4 | | --- | --- | --- | --- | --- | --- | | 720p | 1280×720 | 720×1280 | 960×960 | 1104×832 | 832×1104 | | 1080p | 1920×1080 | 1080×1920 | 1440×1440 | 1648×1248 | 1248×1648 | enum: - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' default: '16:9' example: '16:9' duration: type: number description: |- 동영상 길이(초, 정수) **범위:** - `video_urls` 미전달: `2 ~ 15`, 기본값 `5` - `video_urls` 전달: `2 ~ 10`(10초로 제한) **청구:** 실제 생성된 동영상 길이 기준 minimum: 2 maximum: 15 default: 5 example: 5 seed: type: integer description: |- 랜덤 시드, 기본값은 랜덤 **설명:** - 범위: `1` ~ `2147483647` - 시드를 고정하면 프롬프트 반복 시 변동을 줄이고 재현성을 높입니다 minimum: 1 maximum: 2147483647 example: 42 prompt_extend: type: boolean description: >- 프롬프트 지능 재작성 활성화 여부. 활성화 시 대형 모델이 프롬프트를 최적화하여 단순하거나 설명이 부족한 프롬프트의 결과를 크게 개선합니다. **참고:** 기본값은 `false`입니다. 필드를 생략하거나 `false`를 보내면 재작성이 발생하지 않습니다. 활성화하려면 명시적으로 `true`를 보내세요. default: false example: false callback_url: type: string description: >- 작업 완료 시의 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 상태 코드는 성공으로 간주, 그 외는 재시도 트리거 format: uri example: https://your-domain.com/webhooks/video-task-completed VideoGenerationResponse: type: object properties: created: type: integer description: 작업 생성 타임스탬프 example: 1757169743 id: type: string description: 작업 ID example: task-unified-1757169743-7cvnl5zw model: type: string description: 실제로 사용한 모델명 example: wan2.7-reference-video object: type: string enum: - video.generation.task description: 작업의 구체적인 종류 progress: type: integer description: 작업 진행률 (0-100) minimum: 0 maximum: 100 example: 0 status: type: string description: 작업 상태 enum: - pending - processing - completed - failed example: pending task_info: $ref: '#/components/schemas/VideoTaskInfo' description: 동영상 작업 상세 정보 type: type: string enum: - text - image - audio - video description: 작업 출력 유형 example: video usage: $ref: '#/components/schemas/Usage' description: 사용량 및 청구 정보 ErrorResponse: type: object properties: error: type: object properties: code: type: string description: 오류 코드 식별자 message: type: string description: 오류 설명 type: type: string description: 오류 유형 VideoTaskInfo: type: object properties: can_cancel: type: boolean description: 작업 취소 가능 여부 example: true estimated_time: type: integer description: 예상 완료 시간(초) minimum: 0 example: 120 Usage: type: object description: 사용량 및 청구 정보 properties: billing_rule: type: string description: 청구 규칙 enum: - per_call - per_token - per_second example: per_call credits_reserved: type: number description: 예상 소비 크레딧 minimum: 0 example: 5 user_group: type: string description: 사용자 그룹 카테고리 enum: - default - vip example: default securitySchemes: bearerAuth: type: http scheme: bearer description: |- ## 모든 API는 Bearer Token 인증이 필요합니다 ## **API Key 받기:** [API Key 관리 페이지](https://evolink.ai/dashboard/keys)에서 API Key를 받으세요 **요청 헤더에 추가:** ``` Authorization: Bearer YOUR_API_KEY ``` ````