> ## Documentation Index > Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Wan3.0 전체 파라미터 가이드 > Wan 3.0(올라운드 참조 동영상) 통합 API. `model` 파라미터로 모드를 선택합니다 **3가지 생성 모드:** - **Text-to-Video**(`wan3.0-text-to-video`): 텍스트 프롬프트만으로 동영상 생성 - **Image-to-Video**(`wan3.0-image-to-video`): 시작 프레임 / 시작·종료 프레임으로 화면의 시작과 끝을 엄격하게 제어 - **Reference-to-Video**(`wan3.0-reference-video`): 참조 이미지 + 참조 동영상 + 참조 오디오 + 파일 / 웹페이지 멀티모달 혼합 참조 **공통 기능:** - 최대 **30초** 길이의 동영상 생성 가능 - 비동기 처리 모드, 반환된 작업 ID로 [상태 조회](/ko/api-manual/task-management/get-task-detail) - 생성된 동영상 링크는 24시간 유효하므로 가능한 한 빨리 저장하세요 ## 과금 안내 - **과금 공식**: 과금 시간 = 입력 동영상 길이 + 출력 동영상 길이, 초 단위로 과금 - **해상도 배율**: `480p` = 1x(기준), `720p` = 2x, `1080p` = 4x - 참조 이미지, 참조 오디오, 참조 파일, 웹페이지 링크는 **모두 과금되지 않음** - `duration`에 `-1`(스마트 길이)을 전달하면 상한인 `30`초 기준으로 최대 금액을 선차감하고, 작업 성공 후 실제 산출 길이로 정산하며 차액은 자동으로 환불됩니다 - `audio` 트랙을 켜거나 꺼도 **가격은 동일**합니다 - **실패한 작업은 과금되지 않으며**, 동결된 금액은 전액 환불됩니다 ## OpenAPI ````yaml ko/api-manual/video-series/wan3.0/wan3.0-overview.json POST /v1/videos/generations openapi: 3.1.0 info: title: Wan3.0 전체 모델 API description: Wan 3.0 올라운드 참조 동영상 생성. 하나의 API로 텍스트-비디오, 이미지-비디오, 참조-비디오 세 가지 모드를 모두 제공합니다 license: name: MIT version: 1.0.0 servers: - url: https://api.evolink.ai description: 프로덕션 환경 security: - bearerAuth: [] tags: - name: 비디오 생성 description: AI 비디오 생성 관련 API paths: /v1/videos/generations: post: tags: - 비디오 생성 summary: Wan3.0 전체 모델 API description: >- Wan 3.0(올라운드 참조 동영상) 통합 API. `model` 파라미터로 모드를 선택합니다 **3가지 생성 모드:** - **Text-to-Video**(`wan3.0-text-to-video`): 텍스트 프롬프트만으로 동영상 생성 - **Image-to-Video**(`wan3.0-image-to-video`): 시작 프레임 / 시작·종료 프레임으로 화면의 시작과 끝을 엄격하게 제어 - **Reference-to-Video**(`wan3.0-reference-video`): 참조 이미지 + 참조 동영상 + 참조 오디오 + 파일 / 웹페이지 멀티모달 혼합 참조 **공통 기능:** - 최대 **30초** 길이의 동영상 생성 가능 - 비동기 처리 모드, 반환된 작업 ID로 [상태 조회](/ko/api-manual/task-management/get-task-detail) - 생성된 동영상 링크는 24시간 유효하므로 가능한 한 빨리 저장하세요 ## 과금 안내 - **과금 공식**: 과금 시간 = 입력 동영상 길이 + 출력 동영상 길이, 초 단위로 과금 - **해상도 배율**: `480p` = 1x(기준), `720p` = 2x, `1080p` = 4x - 참조 이미지, 참조 오디오, 참조 파일, 웹페이지 링크는 **모두 과금되지 않음** - `duration`에 `-1`(스마트 길이)을 전달하면 상한인 `30`초 기준으로 최대 금액을 선차감하고, 작업 성공 후 실제 산출 길이로 정산하며 차액은 자동으로 환불됩니다 - `audio` 트랙을 켜거나 꺼도 **가격은 동일**합니다 - **실패한 작업은 과금되지 않으며**, 동결된 금액은 전액 환불됩니다 operationId: createWan30Video requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VideoGenerationRequest' examples: text_to_video: summary: 텍스트-투-비디오 value: model: wan3.0-text-to-video prompt: >- A kitten runs across a rooftop in the moonlight, city neon flickers in the distance, cinematic quality, smooth camera work. duration: 5 quality: 720p aspect_ratio: '16:9' generate_audio: true image_to_video: summary: 이미지-비디오(시작/종료 프레임) value: model: wan3.0-image-to-video prompt: >- A young girl's smile gradually turns into a big laugh, the camera slowly pushes in, and the background light shifts from cool tones to warm tones. image_start: https://example.com/first_frame.jpg image_end: https://example.com/last_frame.jpg duration: 5 quality: 720p reference_to_video: summary: 참조-비디오(멀티모달 소재) value: model: wan3.0-reference-video prompt: >- The character in Video 1 holds Image 3 and plays a soft country folk tune on the chair in Image 4, saying: “What lovely sunshine today.” image_urls: - https://example.com/role.jpg - https://example.com/object.png - https://example.com/guitar.png - https://example.com/chair.png video_urls: - https://example.com/ref_role.mp4 duration: 10 quality: 720p aspect_ratio: adaptive smart_duration: summary: 스마트 길이(모델이 길이를 결정) value: model: wan3.0-text-to-video prompt: >- A high-end smart glasses product ad, minimalist and futuristic, the camera glides over the lens and hinge details and finally settles on the brand logo. duration: -1 quality: 1080p aspect_ratio: '16:9' 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_parameter 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: wan3.0-text-to-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: VideoGenerationRequest: type: object required: - model properties: model: type: string description: 비디오 생성 모델 이름 enum: - wan3.0-text-to-video - wan3.0-image-to-video - wan3.0-reference-video example: wan3.0-text-to-video prompt: type: string description: >- 동영상 생성을 위한 텍스트 프롬프트. 중국어와 영어를 지원하며 **한자/알파벳은 각각 1자로 계산**되고, 최대 길이는 `20000`자이며 초과분은 자동으로 잘립니다(오류가 발생하지 않음) **필수 여부:** `wan3.0-text-to-video`는 필수, `wan3.0-reference-video`는 참조 소재와 함께 둘 중 하나 이상 필요, `wan3.0-image-to-video`는 화면 변화를 설명하도록 전달 권장 **소재 지칭 규칙(참조-비디오):** - "이미지1", "동영상1", "오디오1"로 해당 배열 안의 소재를 지칭합니다(1부터 시작) - 이미지, 동영상, 오디오는 **각각 독립적으로 계산**되므로 "이미지1"과 "동영상1"이 동시에 존재할 수 있습니다 example: >- The character in Video 1 holds Image 3 and plays a soft country folk tune on the chair in Image 4, saying: “What lovely sunshine today.” image_start: type: string format: uri description: >- 시작 프레임 이미지 URL. 생성되는 동영상의 첫 프레임으로 엄격하게 사용됩니다. **`wan3.0-image-to-video`에서만 사용 가능** **이미지 제한:** - 포맷: JPEG, JPG, PNG(투명도 미지원), BMP, WEBP - 해상도: 가로/세로가 `[240, 8000]` 픽셀 - 종횡비: 1:8 ~ 8:1 - 파일 크기: `20MB` 이하 example: https://example.com/first_frame.jpg image_end: type: string format: uri description: >- 종료 프레임 이미지 URL. 생성되는 동영상의 마지막 프레임으로 엄격하게 사용됩니다. **`wan3.0-image-to-video`에서만 사용 가능** **제약:** `image_start`와 함께 사용해야 하며, 종료 프레임만 전달하는 것은 지원되지 않습니다. **이미지 제한:** - 포맷: JPEG, JPG, PNG(투명도 미지원), BMP, WEBP - 해상도: 가로/세로가 `[240, 8000]` 픽셀 - 종횡비: 1:8 ~ 8:1 - 파일 크기: `20MB` 이하 example: https://example.com/last_frame.jpg image_urls: type: array items: type: string format: uri maxItems: 10 description: >- 참조 이미지 URL 배열, **최대 10장**, **`wan3.0-reference-video`에서만 사용 가능**. 주체 캐릭터(인물/동물/사물)나 장면 배경을 제공할 수 있으며, 주체를 포함할 때는 각 이미지에 **단일** 캐릭터만 담는 것을 권장합니다 배열 순서는 프롬프트의 "이미지1, 이미지2……"에 대응합니다 **참고:** 이미지-비디오의 시작/종료 프레임에는 `image_start` / `image_end`를 사용하고 이 필드는 사용하지 마세요 **이미지 제한:** - 포맷: JPEG, JPG, PNG(투명도 미지원), BMP, WEBP - 해상도: 가로/세로가 `[240, 8000]` 픽셀 - 종횡비: 1:8 ~ 8:1 - 파일 크기: `20MB` 이하 example: - https://example.com/ref1.jpg - https://example.com/ref2.png video_urls: type: array items: type: string format: uri maxItems: 5 description: >- 참조 동영상 URL 배열, **최대 5개**, **`wan3.0-reference-video`에서만 사용 가능**. 배열 순서는 프롬프트의 "동영상1, 동영상2……"에 대응합니다 **길이 제한:** - 개별 클립 `1 ~ 15`초 - **합계 15초 이내** - 참조 동영상 총 길이 + 출력 동영상 길이는 **30초를 초과할 수 없음** **🔴 참조 동영상은 과금에 포함됩니다**: 과금 시간 = 입력 동영상 길이 + 출력 동영상 길이. 참조 이미지, 참조 오디오, 파일, 웹페이지는 과금되지 않습니다 **동영상 제한:** - 포맷: mp4, mov - 해상도: 가로/세로가 `[240, 4096]` 픽셀 - 종횡비: 1:8 ~ 8:1 - 파일당 크기: `100MB` 이하 example: - https://example.com/ref_video.mp4 audio_urls: type: array items: type: string format: uri maxItems: 5 description: >- 참조 오디오 URL 배열, **최대 5개**, **`wan3.0-reference-video`에서만 사용 가능**. 배열 순서는 프롬프트의 "오디오1, 오디오2……"에 대응합니다 **⚠️ Wan2.7과 의미가 다릅니다:** Wan2.7의 `audio_urls`는 특정 참조 이미지/참조 동영상에 바인딩되는 **음색**이었지만, Wan3.0의 참조 오디오는 **독립 소재**로 프롬프트에서 "오디오1"로 직접 지칭하며 `model_params.voice_bindings` 음색 바인딩 프로토콜을 **지원하지 않습니다**. Wan2.7에서 마이그레이션할 때 수정에 유의하세요. **길이 제한:** - 개별 클립 `1 ~ 15`초, 합계 15초 이내 - 참조 오디오는 **과금되지 않습니다** **오디오 제한:** - 포맷: wav, mp3 - 파일 크기: `15MB` 이하 example: - https://example.com/ref_audio.mp3 duration: type: integer description: >- 생성할 동영상의 길이(초), 기본값은 `5` **값 설명:** - `2` ~ `30` 사이의 임의의 정수 - `-1`: 스마트 길이. 프롬프트와 입력 소재에 따라 모델이 출력 길이를 자동으로 결정 **스마트 길이의 과금 방식:** 제출 시점에는 모델이 얼마나 긴 영상을 만들지 알 수 없으므로 상한인 `30`초 기준으로 **최대 금액을 선차감**하고, 작업 성공 후 실제 산출 길이로 정산하며 초과 동결분은 자동으로 환불됩니다. 잔액이 최대 선차감액을 감당하지 못하면 명시적인 초 수를 사용하세요. **참조 동영상을 전달할 때의 추가 제약:** - 참조 동영상 총 길이 + 출력 동영상 길이는 **30초를 초과할 수 없음** - 예: 참조 동영상 합계가 10초이면 `duration`은 최대 20까지만 지정 가능 default: 5 example: 5 quality: type: string description: |- 동영상 해상도, 기본값은 `720p` **선택 가능한 값:** - `480p`: 선명도가 낮고 가격이 가장 저렴(과금 기준 등급) - `720p`: 표준 선명도, 기본값이며 가격은 `480p`의 2배 - `1080p`: 고선명도, 가격은 `480p`의 4배 enum: - 480p - 720p - 1080p default: 720p example: 720p aspect_ratio: type: string description: |- 동영상 종횡비, 기본값은 `adaptive` **선택 가능한 값:** - `adaptive`: 자동. 입력 소재의 비율과 프롬프트의 의도에 따라 모델이 적합한 종횡비를 추천하며, 기본값입니다 - `16:9`(가로), `9:16`(세로), `1:1`(정사각형), `4:3`, `3:4` enum: - adaptive - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' default: adaptive example: '16:9' generate_audio: type: boolean description: |- 출력 동영상에 오디오 트랙을 포함할지 여부, 기본값은 `true` **선택 가능한 값:** - `true`: 출력 동영상에 소리(음성, 효과음, 배경 음악)를 포함하며, 기본값입니다 - `false`: 무음 동영상 출력 **소리를 켜든 끄든 가격은 동일**하며 추가 요금이 없습니다. default: true example: true seed: type: integer description: |- 랜덤 시드. 생성 결과를 재현하는 데 사용하며 기본값은 랜덤 **설명:** - 범위: `0` ~ `2147483647` - 시드를 고정하면 프롬프트를 조정할 때 파라미터 변화로 인한 간섭이 줄어 재현성이 높아집니다 minimum: 0 maximum: 2147483647 example: 42 model_params: type: object description: >- 모델 확장 파라미터, **`wan3.0-reference-video`에서만 사용 가능**. `file_url`과 `link_url`은 **상호 배타적**이며 둘 중 하나만 선택할 수 있습니다 properties: file_url: type: string format: uri description: >- 참조 파일 URL, **최대 1개**. 모델이 파일 내용을 자동으로 이해하고 그에 따라 동영상을 생성합니다(예: 제품 PPT를 제품 홍보 영상으로 변환) **`link_url`과 상호 배타적**이며 두 값을 동시에 전달할 수 없습니다 **파일 제한:** - 포맷: docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, md - 파일 크기: `100MB` 이하 - 페이지 수: 50페이지 이하 example: https://example.com/product-deck.pptx link_url: type: string format: uri description: |- 참조 웹페이지 링크, **최대 1개**. 모델이 자동으로 웹페이지를 수집·이해한 뒤 동영상을 생성합니다 **`file_url`과 상호 배타적**이며 두 값을 동시에 전달할 수 없습니다 **제한:** **로그인이 필요 없는** 공개 웹페이지(뉴스, 블로그, 공식 계정 게시글 등)만 파싱할 수 있습니다 example: https://example.com/article/12345 callback_url: type: string description: >- 작업 완료 후 HTTPS 콜백 주소 **콜백 시점:** - 작업 완료(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: 1761313744 id: type: string description: 작업 ID example: task-unified-1774857405-abc123 model: type: string description: 실제 사용된 모델 이름 example: wan3.0-text-to-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/VideoUsage' 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: 165 video_duration: type: integer description: 비디오 길이(초) example: 8 VideoUsage: type: object description: 사용량 및 과금 정보 properties: billing_rule: type: string description: 과금 규칙 enum: - per_call - per_token - per_second example: per_second credits_reserved: type: number description: 예상 소비 크레딧 minimum: 0 example: 50 user_group: type: string description: 사용자 그룹 카테고리 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 ``` ````