Wan 모델 텍스트-투-비디오 API 문서¶

Wan/Alibaba Cloud는 고품질 텍스트-투-비디오 생성 모델을 제공합니다. 이 문서는 Wan/Alibaba Cloud 모델을 사용한 텍스트-투-비디오 생성의 전체 API 인터페이스 사양을 설명합니다.

지원 모델¶

현재 지원되는 모델:

모델	설명
wan2.5-t2v-preview	Wan 2.5 텍스트-투-비디오 생성 모델 (프리뷰)
wan2.6-t2v	Wan 2.6 텍스트-투-비디오 생성 모델

개요¶

Wan 텍스트-투-비디오 기능은 비동기 작업 처리 메커니즘을 제공합니다:

작업 제출: 텍스트 프롬프트를 보내 비디오 생성 작업 생성
상태 조회: task ID로 생성 진행률/상태 조회
결과 획득: 작업 완료 후 생성 비디오 파일 획득

작업 상태 흐름¶

queued → in_progress → completed
                ↓
            failed

queued: 작업이 제출되어 처리 대기 중
in_progress: 작업이 처리 중
completed: 작업 성공 완료, 비디오 생성됨
failed: 작업 실패

API 목록¶

메서드	경로	설명
POST	/v1/video/generations	비디오 생성 작업 제출
GET	/v1/video/generations/{task_id}	작업 상태 조회

사용 예시¶

요청 본문¶

{
  "prompt": "A large hand-shaped marble statue with vines growing on it, on a platform in the middle of a shallow pool of water.",
  "model": "wan2.5-t2v-preview",
  "metadata": {
    "input": {
      "negative_prompt": "trees, animals, outdoors"
    },
    "parameters": {
      "size": "1280*720"
    }
  }
}

전체 요청:

curl -X POST "https://ssanai-workspace.atto-lab.cc/v1/video/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{
    "prompt": "A large hand-shaped marble statue with vines growing on it, on a platform in the middle of a shallow pool of water.",
    "model": "wan2.5-t2v-preview",
    "metadata": {
      "input": {
        "negative_prompt": "trees, animals, outdoors"
      },
      "parameters": {
        "size": "1920*1080"
      }
    }
  }'

요청 파라미터:¶

파라미터	유형	필수	설명
model	문자열	예	모델 이름(예: `wan2.5-t2v-preview`)
prompt	문자열	예	생성할 비디오 콘텐츠를 설명하는 텍스트 프롬프트
metadata	객체	아니오	공식 Wan 요청 형식의 선택 필드를 지정하기 위한 `input`, `parameters` 하위 객체를 포함하는 메타데이터 객체

metadata.input 파라미터:¶

파라미터	유형	필수	설명
negative_prompt	문자열	아니오	비디오에서 제외하고 싶은 요소를 지정하는 네거티브 프롬프트 텍스트
audio_url	문자열	아니오	오디오-비디오 동기화를 위한 사용자 지정 오디오 파일 URL. 이 값을 제공하면 `parameters.audio` 파라미터는 무시됩니다. 지원 모델: wan2.5, wan2.6

metadata.parameters 파라미터:¶

파라미터	유형	필수	설명
prompt_extend	불리언	아니오	지능형 프롬프트 재작성 활성화
watermark	불리언	아니오	비디오에 워터마크 추가
seed	정수	아니오	생성 재현성을 위한 랜덤 시드. 같은 시드를 사용하면 유사한 결과를 얻을 수 있습니다
size	문자열	아니오	비디오 해상도. 참고: wan2.6에서는 480P를 지원하지 않습니다. 해상도 등급별 옵션: 480P 등급 (wan2.5 전용): - `"832480"` (16:9) - `"480832"` (9:16) - `"624624"` (1:1) 720P 등급: - `"1280720"` (16:9) - `"7201280"` (9:16) - `"960960"` (1:1) - `"1088832"` (4:3) - `"8321088"` (3:4) 1080P 등급: - `"19201080"` (16:9) - `"10801920"` (9:16) - `"14401440"` (1:1) - `"16321248"` (4:3) - `"1248*1632"` (3:4)
duration	정수	아니오	비디오 길이(초). 옵션: `5`, `10`, `15` (15초는 wan2.6 전용)
audio	불리언	아니오	자동 더빙/배경 오디오 생성을 활성화합니다. `input.audio_url`을 제공하지 않은 상태에서 `true`로 설정하면 프롬프트와 영상에 맞는 배경 오디오 또는 음악을 자동 생성합니다. 지원 모델: wan2.5, wan2.6. 참고: wan2.2 및 이전 버전은 무음 비디오만 출력합니다
shot_type	문자열	아니오	생성 비디오의 샷 유형(하나의 연속 샷인지, 여러 전환 샷인지)을 지정합니다. 옵션: `"single"`(기본값, 단일 샷 비디오) 또는 `"multi"`(다중 샷 비디오). wan2.6 전용. 참고: 이 파라미터는 `prompt_extend`가 `true`일 때만 적용됩니다. 우선순위: `shot_type > prompt`

오디오 파라미터 참고:

오디오 동작은 input.audio_url과 parameters.audio 파라미터로 제어되며, 우선순위는 audio_url > audio입니다. 다음 3가지 모드를 지원합니다:

무음 비디오 생성: audio_url을 전달하지 않고 audio를 false로 설정
오디오 자동 생성: audio_url을 전달하지 않고 audio를 true로 설정(모델이 프롬프트와 영상 내용에 맞는 배경 오디오/음악을 자동 생성)
사용자 지정 오디오 사용: audio_url 전달(audio 파라미터는 무시되며, 립싱크/리듬 등 오디오 내용에 맞춰 영상이 생성되도록 시도)

1. 비디오 생성 작업 제출¶

엔드포인트:¶

POST /v1/video/generations

요청 헤더:¶

파라미터	유형	필수	설명
Content-Type	문자열	예	application/json
Authorization	문자열	예	Bearer API_KEY

응답 예시:¶

{
  "id": "...",
  "object": "video",
  "model": "wan2.5-t2v-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1765328779
}

응답 필드 설명:¶

필드	유형	설명
id	문자열	작업 ID (후속 작업 상태 조회용)
object	문자열	객체 타입, 고정값 `"video"`
model	문자열	비디오 생성에 사용된 모델
status	문자열	작업 상태(초기값: `"queued"`)
progress	정수	작업 진행률(`0~100`)
created_at	정수	작업 생성 타임스탬프

2. 작업 상태 조회¶

전체 요청¶

curl -X GET "https://ssanai-workspace.atto-lab.cc/v1/video/generations/TASK_ID" \
  -H "Authorization: Bearer API_KEY"

엔드포인트:¶

GET /v1/video/generations/{task_id}

요청 헤더:¶

파라미터	유형	필수	설명
Authorization	문자열	예	Bearer API_KEY

경로 파라미터:¶

파라미터	유형	필수	설명
task_id	문자열	예	작업 ID

응답 예시 (처리 중):¶

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "...",
    "action": "textGenerate",
    "status": "IN_PROGRESS",
    "fail_reason": "",
    "submit_time": 1765328779,
    "start_time": 1765328794,
    "finish_time": 0,
    "progress": "30%",
    "data": {
      "output": {
        "scheduled_time": "2025-12-10 09:06:19.749",
        "submit_time": "2025-12-10 09:06:19.731",
        "task_id": "...",
        "task_status": "RUNNING"
      },
      "request_id": "..."
    }
  }
}

응답 예시 (성공):¶

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "...",
    "action": "textGenerate",
    "status": "SUCCESS",
    "fail_reason": "<OUTPUT_URL>",
    "submit_time": 1765328779,
    "start_time": 1765328794,
    "finish_time": 1765328947,
    "progress": "100%",
    "data": {
      "output": {
        "actual_prompt": "<EDITED_PROMPT>",
        "end_time": "2025-12-10 09:08:53.863",
        "orig_prompt": "A large hand-shaped marble statue with vines growing on it, on a platform in the middle of a shallow pool of water.",
        "scheduled_time": "2025-12-10 09:06:19.749",
        "submit_time": "2025-12-10 09:06:19.731",
        "task_id": "...",
        "task_status": "SUCCEEDED",
        "video_url": "<OUTPUT_URL>"
      },
      "request_id": "...",
      "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "1920*1080"
      }
    }
  }
}

data.data.output.video_url 필드에서 비디오 URL을 확인할 수 있습니다.

응답 예시 (실패):¶

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "...",
    "action": "textGenerate",
    "status": "FAILURE",
    "fail_reason": "task failed, code: InvalidParameter , message: image_url must provided",
    "submit_time": 1765407269,
    "start_time": 1765407278,
    "finish_time": 1765407294,
    "progress": "100%",
    "data": {
      "output": {
        "code": "InvalidParameter",
        "end_time": "2025-12-11 06:54:49.934",
        "message": "image_url must provided",
        "scheduled_time": "2025-12-11 06:54:29.557",
        "submit_time": "2025-12-11 06:54:29.529",
        "task_id": "...",
        "task_status": "FAILED"
      },
      "request_id": "..."
    }
  }
}

응답 필드 설명:¶

필드	유형	설명
code	문자열	응답 상태 코드(`"success"`는 성공)
message	문자열	응답 메시지
data	객체	작업 데이터 객체
data.task_id	문자열	작업 ID
data.status	문자열	작업 상태: `IN_PROGRESS`, `SUCCESS`, `FAILURE`
data.progress	문자열	작업 진행률(퍼센트)
data.data.output.video_url	문자열	비디오 접근 URL(작업 성공 시)
data.data.output.task_status	문자열	작업 상태: `RUNNING`, `SUCCEEDED`, `FAILED`
data.data.usage	객체	사용량 통계(작업 성공 시)
data.data.usage.video_count	정수	생성된 비디오 개수
data.data.usage.video_duration	정수	비디오 길이(초)
data.data.usage.video_ratio	문자열	비디오 해상도

Wan 모델 텍스트-투-비디오 API 문서¶

지원 모델¶

개요¶

작업 상태 흐름¶

API 목록¶

사용 예시¶

요청 본문¶

요청 파라미터:¶

metadata.input 파라미터:¶

metadata.parameters 파라미터:¶

1. 비디오 생성 작업 제출¶

엔드포인트:¶

요청 헤더:¶

응답 예시:¶

응답 필드 설명:¶

2. 작업 상태 조회¶

전체 요청¶

엔드포인트:¶

요청 헤더:¶

경로 파라미터:¶

응답 예시 (처리 중):¶

응답 예시 (성공):¶

응답 예시 (실패):¶

응답 필드 설명:¶

관련 링크¶