Wan API 연동 가이드

Wan API 연결제목 링크 복사

API 기본 URL은 https://api.wanapi.app입니다. API 키 설정에서 키를 생성한 뒤 Authorization: Bearer YOUR_API_KEY로 전송하세요. 키는 서버에 보관하세요. 플레이그라운드는 웹사이트 세션으로 인증하며 같은 계정 잔액에서 비용을 차감합니다. 브라우저에 키를 붙여 넣을 필요가 없습니다.

API를 사용하려면 계정이 활성화되어 있고 잔액이 충분해야 합니다. 현재 요금은 요금 페이지에서 확인하세요. 각 모델에는 전용 엔드포인트와 모델 페이지가 있습니다.

GET /v1/models는 해당 키로 사용할 수 있는 모델 목록을 반환합니다. 더 높은 해상도를 선택해도 모델이 자동으로 변경되지는 않습니다.

요청 필드제목 링크 복사

네 모델 모두 아래의 네이티브 필드 14개를 사용합니다. 프롬프트 또는 하나 이상의 미디어 입력을 제공하세요. 프레임 입력은 참조 입력, file, link와 함께 사용할 수 없습니다. file과 link도 동시에 사용할 수 없습니다.

작업이 끝날 때까지 직접 접근할 수 있는 안정적인 미디어 URL을 사용하세요. 동영상 길이는 제한된 범위의 HTTP Range 요청으로 확인합니다. 동영상 서버는 이러한 요청을 지원하고 읽을 수 있는 MP4/MOV 길이 메타데이터를 제공해야 합니다. 길이 확인 시 리디렉션은 따라가지 않습니다. 사설 네트워크 URL은 지원하지 않습니다. 참조 동영상과 출력 동영상의 합산 길이는 30초를 넘을 수 없습니다. 플레이그라운드는 최대 32 MiB의 JSON 요청 본문을 허용합니다. 더 큰 입력에는 URL을 사용하세요.

작업 상태 조회 및 동영상 다운로드제목 링크 복사

모든 모델의 제출 엔드포인트는 외부 API에서 사용할 작업 ID를 반환합니다. 다른 처리를 하기 전에 먼저 이 ID를 저장하세요.

{
  "task_info": {
    "id": "task_EXAMPLE",
    "status": "pending"
  }
}

해당 모델 절의 조회 예시를 사용하세요. 5초 간격으로 시작하고 일시적인 오류가 발생하면 대기 시간을 늘리세요. 각 작업의 모델 ID와 작업 ID를 함께 보관하고, 다른 모델 엔드포인트로 조회하지 마세요.

네이티브 상태 값은 pending, processing, completed, failed입니다. 완료된 응답에는 완전한 Bunny CDN 서명 URL을 담은 videos 배열이 포함됩니다.

{
  "task_info": { "id": "task_EXAMPLE", "status": "completed" },
  "videos": ["https://reapiflexible.b-cdn.net/flexible/v1/expires/2026-11/20261113T06/wanapi-task_EXAMPLE/video.mp4?token=HS256_SIGNATURE&expires=1794550071"]
}

반환된 URL을 재생이나 다운로드에 바로 사용할 수 있습니다. 이 URL에는 API 키나 Authorization 헤더가 필요하지 않습니다. 파일에는 저장소의 기존 보관 정책이 적용됩니다. 작업을 다시 조회해도 동영상이 다시 생성되거나 추가 요금이 부과되지 않으며 파일의 보관 기한도 연장되지 않습니다. 계속 보관할 파일은 자신의 저장소에 저장하세요. 작업 조회에는 API 키가 필요하며 해당 계정이 소유한 작업만 반환됩니다.

동기 및 백그라운드 Responses제목 링크 복사

Responses API를 사용하는 클라이언트는 POST /v1/responses에 모델 ID, 문자열 input, 동일한 네이티브 생성 필드를 전달할 수 있습니다. prompt 대신 input을 사용하세요. reference_images와 같은 네이티브 미디어 필드는 최상위 필드로 전달합니다.

{
  "model": "wan3.0-video",
  "input": "A blue ball rolls across a white table.",
  "resolution": "480p",
  "duration": 2,
  "background": true
}

background: true를 사용하면 응답 ID를 저장한 뒤 GET /v1/responses/{response_id}를 주기적으로 조회하세요. background가 없으면 HTTP 요청은 생성이 완료될 때까지 대기합니다. stream: true는 대기 중에 서버 전송 이벤트(SSE)를 사용합니다. 최종 assistant 출력에는 서명된 동영상 URL이 포함됩니다. 이 URL 자체가 접근 권한을 부여하므로 비공개로 보관하고 실수로 공개하지 마세요. 생성 시간이 길거나 프록시의 요청 제한 시간이 짧다면 네이티브 작업 제출 또는 백그라운드 Responses를 권장합니다.

동기 요청의 연결이 끊기거나 제한 시간을 초과해도 생성은 취소되지 않습니다. 작업은 서버에 남습니다. 같은 생성 요청을 자동으로 다시 제출하지 마세요.

과금 및 오류 처리제목 링크 복사

비용은 해당 모델의 해상도별 초당 요금에 과금 대상 초를 곱해 계산합니다. 참조 동영상과 출력 동영상의 길이가 모두 포함됩니다. 텍스트, 이미지, 오디오 입력은 동영상 과금 초를 추가하지 않습니다. 참조 동영상이 없는 고정 길이 요청은 요청한 출력 길이에 해당하는 비용을 예약합니다. 자동 길이 및 참조 동영상 요청은 과금 대상 최대 30초에 해당하는 비용을 예약한 뒤 실제 측정 사용량으로 정산하고 사용하지 않은 예약 금액을 반환합니다. 생성에 실패하면 예약 금액이 해제됩니다. 상태 조회는 새 생성 작업을 만들거나 비용을 다시 청구하지 않습니다.

• 잘못된 매개변수: 요청을 수정한 뒤 다시 제출하세요. 알 수 없는 네이티브 필드는 거부됩니다.
• 잔액 부족: 새로운 유료 요청을 제출하기 전에 잔액을 충전하세요. 키의 사용 한도는 계정 잔액을 제공하지 않습니다.
• 요청 제한 또는 일시적인 상태 조회 실패: 조회만 재시도하되 대기 시간을 늘리고 최대 대기 시간을 정하세요.
• 제출 시간 초과, 네트워크 중단 또는 작업 ID 누락: 제출 결과가 불확실할 수 있습니다. 두 번째 유료 작업이 생성될 수 있으므로 POST 요청을 자동으로 반복하지 마세요.
• 작업 실패: 작업 실패 상태와 상태 조회 불가를 구분해 표시하세요.
• 다운로드 실패: 새 생성을 시작하기 전에 이미 완료된 작업의 다운로드를 재시도하세요.

생성 요청은 자동으로 재시도되거나 다른 모델로 전환되지 않습니다. 취소, 웹훅, 멱등성 키에 대한 API 규약은 제공하지 않습니다. 제출 결과가 불확실해 확인이 필요하면 작업 ID를 보관하고 지원팀에 문의하세요.