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

Wan/Alibaba Cloud는 고품질 비디오-투-비디오 생성 모델을 제공합니다. 이 문서는 Wan/Alibaba Cloud 모델을 사용한 비디오-투-비디오 생성의 전체 API 인터페이스 사양을 설명합니다. Wan 비디오-투-비디오 모델은 입력 비디오의 캐릭터와 음성을 프롬프트와 결합하여 캐릭터 일관성을 유지한 새 비디오를 생성합니다.

개요¶

지원 모델¶

현재 지원되는 모델:

모델	설명
wan2.6-r2v	Wan 2.6 비디오-투-비디오 생성 모델

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

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

작업 상태 흐름¶

queued → in_progress → completed
                ↓
            failed

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

주요 기능¶

기본 기능: 비디오 길이(5초/10초)를 선택하고, 해상도(720P/1080P)를 지정하며, 워터마크를 추가할 수 있습니다
다중 샷 내러티브: 샷 전환 간 피사체 일관성을 유지하면서 여러 샷으로 구성된 비디오를 생성할 수 있습니다

API 목록¶

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

사용 예시¶

1. 단일 캐릭터 참조¶

영상에서 캐릭터의 외형과 음성을 참조하고 shot_type을 multi로 설정해 다중 샷 비디오를 생성합니다.

요청 본문:

{
  "prompt": "character1 drinks bubble tea while dancing spontaneously to the music.",
  "model": "wan2.6-r2v",
  "metadata": {
    "input": {
      "reference_video_urls": [
        "https://example.com/reference-video.mp4"
      ]
    },
    "parameters": {
      "size": "1280*720",
      "duration": 5,
      "shot_type": "multi"
    }
  }
}

2. 다중 캐릭터 참조¶

캐릭터와 소품의 참조 영상을 기반으로 프롬프트에서 관계를 정의하고 shot_type을 multi로 설정해 다중 샷 비디오를 생성합니다. 프롬프트에서 동일 캐릭터를 여러 번 참조할 수 있습니다.

요청 본문:

{
  "prompt": "character1 and character2 talk to each other in an office.",
  "model": "wan2.6-r2v",
  "metadata": {
    "input": {
      "reference_video_urls": [
        "https://example.com/character1-video.mp4",
        "https://example.com/character2-video.mp4"
      ],
      "negative_prompt": "white walls"
    },
    "parameters": {
      "size": "1280*720",
      "duration": 10,
      "shot_type": "multi",
      "watermark": true
    }
  }
}

전체 요청:

curl -X POST "https://ssanai-workspace.atto-lab.cc/v1/video/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{
    "prompt": "character1 and character2 talk to each other in an office.",
    "model": "wan2.6-r2v",
    "metadata": {
      "input": {
        "reference_video_urls": [
          "https://example.com/character1-video.mp4",
          "https://example.com/character2-video.mp4"
        ],
        "negative_prompt": "white walls"
      },
      "parameters": {
        "size": "1280*720",
        "duration": 10,
        "shot_type": "multi",
        "watermark": true
      }
    }
  }'

요청 파라미터:¶

파라미터	유형	필수	설명
model	문자열	예	모델 이름. 현재 지원 모델은 `wan2.6-r2v` 하나입니다
prompt	문자열	예	생성할 비디오 콘텐츠를 설명하는 텍스트 프롬프트. 다중 캐릭터 시나리오에서는 `character1`, `character2` 같은 식별자로 서로 다른 참조 비디오를 지정할 수 있습니다
metadata	객체	아니오	공식 Wan 요청 형식의 선택 필드를 지정하기 위한 `input`, `parameters` 하위 객체를 포함하는 메타데이터 객체

metadata.input 파라미터:¶

파라미터	유형	필수	설명
reference_video_urls	배열[문자열]	예	참조 비디오 URL 배열입니다. 최대 3개 비디오를 지원합니다. 다중 비디오 사용: 여러 비디오를 사용할 경우 배열 내 URL 순서가 캐릭터 순서를 정의합니다. 첫 번째 URL은 `character1`, 두 번째 URL은 `character2`에 대응합니다. 비디오 요구사항: - 각 참조 비디오는 캐릭터 1명만 포함해야 합니다(예: character1은 소녀, character2는 알람시계) - 형식: MP4 또는 MOV - 길이: 2~30초 - 파일 크기: 100MB 이하 - URL: HTTP 또는 HTTPS 지원
negative_prompt	문자열	아니오	비디오에서 제외할 요소를 지정하는 네거티브 프롬프트 텍스트

metadata.parameters 파라미터:¶

파라미터	유형	필수	설명
size	문자열	아니오	비디오 해상도. 기본값은 `"19201080"`(1080P)입니다. 옵션: 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`
shot_type	문자열	아니오	생성 비디오의 샷 유형을 지정합니다. 옵션: `"single"`(기본값, 단일 샷 비디오) 또는 `"multi"`(샷 전환 간 피사체 일관성을 유지하는 다중 샷 비디오)
watermark	불리언	아니오	비디오에 워터마크 추가
seed	정수	아니오	랜덤 시드 값입니다. 범위는 `[0, 2147483647]`입니다. 지정하지 않으면 시스템이 자동 생성합니다. 재현성을 높이려면 고정 시드를 사용하세요. 단, 생성은 확률적이므로 동일 시드라도 결과가 항상 완전히 같지는 않을 수 있습니다. 예: `12345`

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

엔드포인트:¶

POST /v1/video/generations

요청 헤더:¶

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

응답 예시:¶

{
  "id": "...",
  "object": "video",
  "model": "wan2.6-r2v",
  "status": "queued",
  "progress": 0,
  "created_at": 1766086029
}

응답 필드 설명:¶

필드	유형	설명
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": 1766086029,
    "start_time": 1766086038,
    "finish_time": 0,
    "progress": "30%",
    "data": {
      "output": {
        "scheduled_time": "2025-12-19 03:27:09.887",
        "submit_time": "2025-12-19 03:27:09.859",
        "task_id": "...",
        "task_status": "RUNNING"
      },
      "request_id": "..."
    }
  }
}

응답 예시 (성공):¶

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "...",
    "action": "textGenerate",
    "status": "SUCCESS",
    "fail_reason": "<OUTPUT_URL>",
    "submit_time": 1766086029,
    "start_time": 1766086038,
    "finish_time": 1766086419,
    "progress": "100%",
    "data": {
      "output": {
        "end_time": "2025-12-19 03:33:31.045",
        "orig_prompt": "character1 and character2 talk to each other in an office.",
        "scheduled_time": "2025-12-19 03:27:09.887",
        "submit_time": "2025-12-19 03:27:09.859",
        "task_id": "...",
        "task_status": "SUCCEEDED",
        "video_url": "<OUTPUT_URL>"
      },
      "request_id": "...",
      "usage": {
        "SR": 720,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "size": "1280*720",
        "video_count": 1,
        "video_ratio": "1280*720"
      }
    }
  }
}

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

응답 예시 (실패):¶

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "...",
    "action": "textGenerate",
    "status": "FAILURE",
    "fail_reason": "task failed, code: InvalidParameter , message: The size is not match xxxxxx",
    "submit_time": 1766086029,
    "start_time": 1766086038,
    "finish_time": 1766086419,
    "progress": "100%",
    "data": {
      "output": {
        "code": "InvalidParameter",
        "end_time": "2025-12-19 03:33:31.045",
        "message": "The size is not match xxxxxx",
        "scheduled_time": "2025-12-19 03:27:09.887",
        "submit_time": "2025-12-19 03:27:09.859",
        "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(작업 성공 시). 링크 유효시간은 24시간입니다
data.data.output.task_status	문자열	작업 상태: `RUNNING`, `SUCCEEDED`, `FAILED`
data.data.output.orig_prompt	문자열	원본 입력 프롬프트
data.data.usage	객체	사용량 통계(작업 성공 시)
data.data.usage.input_video_duration	정수	입력 참조 비디오 전체 길이(초)
data.data.usage.output_video_duration	정수	출력 비디오 길이(초), `parameters.duration` 값과 동일
data.data.usage.duration	실수	과금에 사용되는 총 비디오 길이(초). 계산식: `duration = input_video_duration + output_video_duration`
data.data.usage.SR	정수	생성 비디오 해상도(예: `720`)
data.data.usage.video_ratio	문자열	생성 비디오 해상도(형식: `"widthheight"`, 예: `"1280720"`)
data.data.usage.video_count	정수	생성된 비디오 수(고정값: `1`)

중요 참고 사항¶

데이터 보관 기간: task_id와 비디오 URL은 24시간 동안 보관됩니다. 이후에는 조회하거나 다운로드할 수 없습니다.
콘텐츠 검수: 입력 프롬프트와 출력 비디오는 모두 콘텐츠 검수를 거칩니다. 금지 콘텐츠가 포함된 요청은 "IPInfringementSuspect" 또는 "DataInspectionFailed" 오류를 반환합니다.
네트워크 접근 설정: 비디오 링크는 OSS(Object Storage Service)에 저장됩니다. 보안 정책으로 외부 OSS 링크 접근이 제한된다면, 관련 OSS 도메인을 네트워크 허용 목록에 추가하세요.
과금 안내:
과금은 **입력 비디오 + 출력 비디오**의 합산 길이를 기준으로 초 단위로 계산됩니다
API 호출 결과 task_status가 SUCCEEDED이고 비디오가 정상 생성된 경우에만 과금됩니다
모델 호출 실패나 처리 오류는 과금되지 않으며 무료 할당량도 차감되지 않습니다
입력 비디오 과금 길이: 각 참조 비디오 길이를 절사한 값의 합이며, 입력 과금 길이 총합은 **최대 5초**입니다
출력 비디오 과금 길이: 모델이 성공적으로 생성한 비디오의 길이(초)입니다
참조 비디오 개수: 참조 비디오는 1~3개를 지원합니다. 단일 캐릭터는 1개, 다중 캐릭터는 여러 개 비디오를 사용하세요.

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

개요¶

지원 모델¶

작업 상태 흐름¶

주요 기능¶

API 목록¶

사용 예시¶

1. 단일 캐릭터 참조¶

2. 다중 캐릭터 참조¶

요청 파라미터:¶

metadata.input 파라미터:¶

metadata.parameters 파라미터:¶

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

엔드포인트:¶

요청 헤더:¶

응답 예시:¶

응답 필드 설명:¶

2. 작업 상태 조회¶

전체 요청¶

엔드포인트:¶

요청 헤더:¶

경로 파라미터:¶

응답 예시 (처리 중):¶

응답 예시 (성공):¶

응답 예시 (실패):¶

응답 필드 설명:¶

중요 참고 사항¶

관련 링크¶