WaveSpeedAI

WAN 2.5 API Quickstart, WaveSpeed에 출시: 인증, 매개변수 및 예제 요청

WAN 2.5 API Quickstart, WaveSpeed에 출시: 인증, 매개변수 및 예제 요청

안녕하세요, 저는 도라입니다. 원래 이번 주에 WaveSpeed의 WAN 2.5 API를 시도할 계획은 없었습니다. 작은 불편함이 저를 그쪽으로 밀어냈습니다: 초안을 위해 일관된 이미지 변형이 필요했는데, 제 평소 도구들은 너무 클릭이 많거나 과하게 똑똑했습니다. 저는 지루하고 신뢰할 수 있는, 스크립트로 작성할 수 있고, 버전 관리가 되고, 쉽게 롤백할 수 있는 것을 원했습니다.

그래서 문서를 열고 차를 끓이고 작은 스크립트를 작성했습니다. 이것은 2026년 1월에 테스트한, 윤기 없는, 그 과정에서 주목한 것들입니다. “기능”에 관한 것이라기보다는 한번 제자리에 놓이면 일을 더 가볍게 만든 부분들입니다.

API 개요

현대의 어떤 AI API라도 건드려본 적이 있다면, WaveSpeed의 WAN 2.5에 대한 접근 방식이 익숙할 것입니다. HTTP in, JSON out. 프롬프트(그리고 때로 이미지)를 보내면, 완성된 결과물이나 폴링할 수 있는 작업 ID를 반환합니다.

코드를 작성하기 전에 주의 깊게 봐야 할 몇 가지 기본 사항이 있습니다:

  • 버전 관리: WAN 2.5는 별개의 버전으로 제공되며, 이는 재현성 측면에서 중요합니다. 저는 “최신” 별칭보다는 URL의 명시적 버전 경로에 고수했습니다. 이 작은 선택이 나중의 나를 무언의 동작 변화로부터 구합니다.
  • 모드: 일부 작업 부하는 동기식(작고 빠름)이고, 다른 작업은 작업으로 분기합니다. 더 높은 해상도 생성이나 배치 작업을 하는 경우, 상태 엔드포인트나 웹훅이 있는 비동기 흐름을 예상하세요.
  • 형식: JSON 응답은 일반적으로 상태, 자산 URL 또는 base64 페이로드, 그리고 일부 메타데이터(시드, 스텝, 타이밍)를 포함합니다. 저는 메타데이터를 유지합니다, 나중에 모양을 재현하고 싶을 때 유용합니다.
  • 제한: 이미지 크기, 스텝 수, 동시성이 제한됩니다. 기본값은 초안에 충분했지만, 해상도를 올리려고 시도하면 한계에 도달했습니다. 속도 제한에 대한 자세한 내용은 아래를 참조하세요.

간단히 말해서: REST에 편하다면 명확한 경로입니다. 핵심은 몇 가지 지루한 부분(키, 매개변수, 재시도)을 올바르게 하여 그것들을 잊을 수 있도록 하는 것입니다.

이 단순성은 우리가 WaveSpeed를 구축한 방식의 일부입니다. 저는 WAN 2.5(및 다른 모델)를 스크립트로 작성할 수 있고, 버전 관리되고, 최선의 의미에서 지루하게 느끼고 싶었습니다. 이것을 직접 연결하는 경우, 여기에서 탐색할 수 있습니다.

인증 & 키

나는 대시보드에서 WaveSpeed API 키를 생성하고 환경 변수에 넣었습니다. 특별한 것은 없지만, 파일을 통해 비밀을 추적하는 것을 피했습니다.

  • WaveSpeed의 계정 설정에서 키를 받습니다. 조직/프로젝트에 연결됩니다.
  • 로컬에 환경 변수로 저장합니다: WAVESPEED_API_KEY. 저는 개발용 .env 파일과 실행용 CI의 비밀 저장소를 사용했습니다.
  • 헤더에 Bearer 인증을 사용합니다: Authorization: Bearer $WAVESPEED_API_KEY.
  • 키를 순환시키는 경우, 트래픽이 적은 시간대에 하세요. 저는 긴 작업을 방해한 예정된 순환으로 조용한 방식으로 배웠습니다.

팀이 범위가 지정된 키가 필요하면 대시보드 설정을 확인하세요. 나는 자동화에 연결된 모든 것에 대해 최소 특권 경로를 선호합니다. 한 가지 작은 마찰: 여러 머신에서 실행 중인 경우, 호스트 또는 서비스별로 키를 명확하게 레이블링하면, 나중에 사용량을 감사할 때 도움이 됩니다.

필수 매개변수

정확한 이름은 엔드포인트에 따라 다를 수 있지만, WaveSpeed의 Wan 2.5에 사용한 최소 형태는 다음과 같습니다. 이것들을 뼈대로 취급하고, 계정의 공식 문서에서 필드 이름을 확인하세요.

  • model: wan-2.5(또는 계획에서 가장 가까운 정확한 문자열)로 명시적으로 설정합니다. 업데이트 전반에 걸쳐 동작을 안정적으로 유지합니다.
  • input: 프롬프트 문자열. 저는 짧고 구체적으로 유지했습니다. WAN은 형용사 수프보다 명확한, 간단한 표현에 더 잘 반응하는 경향이 있습니다.
  • mode or task: 이미지 생성 대 변형/업스케일. 소스 이미지를 전달하는 경우, 이것이 중요합니다.
  • output: 기본적으로 이미지 URL을 요청했습니다. Base64가 있지만, URL이 메모리에 더 친절합니다.

모델을 명시적으로 설정하는 것을 잊으면, 합리적인 기본값을 얻지만 결과는 실행 전반에 걸쳐 미묘하게 변했습니다. 틀린 것은 아니지만, 재현성이 없습니다. 버전을 잠그는 것이 그 흔들림을 제거했습니다.

선택적 매개변수

실제 제어가 여기 있습니다. 저는 첫 날에 몇 개만 건드렸습니다.

  • seed: 일단 모양이 마음에 들면 이것을 켭니다. 변형의 분위기를 안정화합니다.
  • steps: 더 높은 스텝은 시간과 크레딧의 비용으로 디테일을 밀어낼 수 있습니다. 저는 작은 증분(예: 24 → 32)으로 범프하고 반환을 지켜봤습니다.
  • guidance or cfg_scale: 프롬프트에 대한 준수를 강화합니다. 너무 높으면 깨지기 쉬워집니다.
  • size or resolution: 여기가 비용이 점프합니다. 저는 작은 초안을 만들고 최종을 대상 크기로 다시 실행합니다.
  • image: 변형의 경우, 소스 이미지 URL을 전달하거나 업로드합니다. 지원되는 경우 강도 매개변수와 쌍을 이룹니다.
  • safety or moderation flags: 워크플로우가 정말 커스텀 처리가 필요하지 않은 한 켜두세요.
  • user or metadata: 나중에 로그에서 실행을 추적하기 위해 요청 ID나 프로젝트 태그를 추가합니다.

작은 관찰: 두 개의 노브를 동시에 변경하면 무엇이 도움이 되었는지 알기 어려워졌습니다. 저는 실행당 한 가지를 변경했고 코멘트에 노트를 유지했습니다. 구식이지만 작동했습니다.

샘플 요청 패턴

저는 세 가지 간단한 형태를 시도했습니다: 빠른 curl, 작은 Python 스크립트, 비동기의 백그라운드 작업.

동기식 초안 (curl)

이것은 다른 것을 연결하기 전에 내 키와 프롬프트를 정신 검사하기에 충분했습니다.

예제 엔드포인트, 계정 및 지역에 대한 문서에서 정확한 경로를 확인하세요:

POST https://api.wavespeed.ai/wan/v2.5/generations

헤더:

  • Authorization: Bearer $WAVESPEED_API_KEY
  • Content-Type: application/json

본문 (최소):

{
  "model": "wan-2.5",
  "input": "quiet studio light, sketch on kraft paper",
  "output": { "format": "url" }
}

내가 주의한 것:

  • 결과와 메타데이터가 있는 200 → 괜찮습니다.
  • 작업 ID가 있는 202 → 비동기 흐름으로 전환합니다.
  • 4xx → 페이로드 또는 인증에 뭔가 빠졌습니다.

작은 Python 헬퍼

헤더, 타임아웃, json을 처리하는 작은 함수를 작성했습니다. URL을 반환하거나 깔끔한 예외를 발생시켰습니다. 마법 같은 것은 없고, 두 번 생각하지 않는 종류의 래퍼일 뿐입니다.

실용적인 부분:

  • 짧은 연결 타임아웃과 약간 더 긴 읽기 타임아웃을 설정합니다.
  • 429를 재시도 및 지터로 처리합니다.
  • 각 실행의 시드, 스텝, 크기를 기록합니다.

비동기 흐름 (작업)

더 큰 이미지나 배치의 경우, 저는 202와 작업 ID를 받았습니다. 루프는 간단했습니다:

  1. POST 작업,
  1. 몇 초마다 GET /jobs/{id} 폴링,
  2. 최종 상태에서 중지(성공/실패),
  3. 자산 URL 가져오기.

스택이 웹훅을 좋아하면 WaveSpeed도 콜백을 제공합니다. 저는 처음에 폴링에 고수했습니다, 설정 중 움직이는 부분이 하나 적습니다.

오류 코드

편집기 옆에 작은 맵을 유지했습니다. 예상보다 빨리 보상했습니다.

  • 400 Bad Request: 보통 필드 이름이나 타입 불일치입니다. 저는 한 번 크기를 객체가 아닌 문자열로 전송했습니다. 수정은 저하고 메시지를 읽으니 명백했습니다.
  • 401 Unauthorized: 키가 누락되었거나 형식이 잘못되었습니다. Bearer 헤더와 후행 공백을 확인하세요.
  • 403 Forbidden: 키는 존재하지만 엔드포인트 또는 모델 계층에 대한 범위가 없습니다.
  • 404 Not Found: 잘못된 엔드포인트 경로 또는 만료된 작업 ID입니다.
  • 409 Conflict: 이미 정착한 작업을 업데이트할 때 이것을 볼 수 있습니다. 다시 폴링하고, 계속 밀지 마세요.
  • 429 Too Many Requests: 분당 또는 조직당 제한을 초과했습니다. 지수 재시도로 물러서세요.
  • 500/503 Server Errors: 제 테스트에서 드물지만, 계획하세요. 짧은 재시도 루프가 내 스크립트를 진정시켰습니다.

도움이 된 작은 습관: 나는 오류 코드와 요청 ID(있는 경우)를 로그에 버블했습니다. 뭔가 이상하면, 지원팀은 그 ID를 사용하여 추적할 수 있습니다.

속도 제한

동시성으로 게으를 때 속도 제한에 도달했습니다. 하기 쉽고, 피하기 더 쉽습니다.

작동한 것:

  • 헤더 존중: 많은 엔드포인트는 속도 헤더를 반환합니다(예: 남은, 리셋 시간). 헤더 이름은 다를 수 있으니 문서를 확인하되, 읽을 가치가 있습니다.
  • 토큰 버킷 또는 간단한 큐를 사용합니다. 버스트 대신 작고 꾸준한 드립으로 스크립트를 제한했습니다. 시스템이 숨을 쉬었고, 저도 그랬습니다.
  • 초안과 최종을 분리합니다. 초안은 작고 빠르게 실행할 수 있습니다: 최종은 백그라운드에서 하나씩 실행할 수 있습니다.
  • 반복을 캐시합니다. 프롬프트를 테스트하는 경우, 같은 호출을 태우지 않도록 이전 결과를 몇 분 동안 유지합니다.

나는 또한 매우 평범한 백오프를 구축했습니다: 1초의 기본 지연, 각 429에서 배가, 30초의 상한선, 최대 4회 재시도. 서두르지 않은 느낌이 들었고 서비스를 독살하는 것을 피했습니다.

비용 안전장치

이것이 내 주요 걱정이었습니다. 이미지 작업은 당신이 차를 만드는 동안 백그라운드에서 크레딧을 입수할 수 있습니다.

첫 날에 설정한 몇 가지 보호:

  • 대시보드의 예산 상한: 월간 상한선을 설정하고 그 아래 이메일 알림을 설정했습니다. 팀이 키를 공유하면, 알림이 루프를 조기에 포착하는 데 도움이 됩니다.
  • 요청당 상한선: 나는 크기와 스텝을 제한 하에 살도록 강제했습니다. “어? 4K 모든 것.” 나를 구했습니다.
  • 초안 우선 워크플로우: 작은 미리보기(낮은 해상도, 적은 스텝)를 실행하고 보관함만 업스케일합니다. 이것이 첫 오후에 지출을 절반 이상 줄였습니다.
  • 시드 규칙: 일단 좋아하는 방향을 찾으면, 시드를 고정하고 한 번에 하나의 매개변수를 변경합니다. 더 적은 블라인드 실행: 더 의도적인 것들.
  • 비용이 있는 로그: 응답에 크레딧이나 사용량 필드가 포함되어 있으면(일부 엔드포인트 하면) 저장합니다. 그렇지 않으면, 해상도 및 스텝을 기반으로 추정하고 그것이 추정이라고 기록합니다.

나는 또한 내 스크립트에 부드러운 킬 스위치를 넣었습니다: 하루의 사용량이 임계값을 초과하면, 새로운 작업은 일시 중지되고 Slack에 메시지를 게시했습니다. 우아하지는 않지만, 제약에 대해 정직합니다.

처음에는 시간을 절약하지 못했습니다. 주의를 절약했습니다. 몇 번의 실행 후, 안전장치는 배경으로 사라지고, 미터 대신 일에 대해 다시 생각할 수 있었습니다.