WaveSpeedAI

WaveSpeed에서 Z-Image-Turbo API 사용하는 방법 (단계별 가이드)

WaveSpeed에서 Z-Image-Turbo API 사용하는 방법 (단계별 가이드)

작은 것이 나를 여기로 이끌었습니다. 저는 Dora입니다. 그날, 저는 랜딩 페이지 변형을 위한 깔끔한 제품 사진이 필요했고, 제 평소의 이미지 도구들은 이 작업보다 무거워 보였습니다. 저는 Z-Image-Turbo​ ​​​API​에 대해 계속 듣고 있었습니다. 시끄러운 종류의 언급이 아니라, 조용히 변경 로그와 엔지니어링 노트에 나타나는 것 같았습니다. 그래서 저는 시도해 봤습니다.

저는 2026년 1월 말 일주일 동안 주로 간단한 마케팅 비주얼과 프로토타입용 컨셉 텍스처를 몇 개 생성하는 데 사용했습니다. 특별한 것은 없었습니다. 저는 스택을 다시 작업하지 않고도 어디에 맞는지 보고 싶었습니다. 도움이 된 것, 그렇지 않은 것, 그리고 어떻게 문제없이 연결했는지에 대해 설명하겠습니다.

필수 요구사항

WaveSpeed 계정 생성

먼저 WaveSpeed 계정을 생성했습니다. 프로세스는 기본적이었습니다: 이메일, 비밀번호, 인증. 놀라운 것은 없었습니다. 저는 대시보드가 저를 테스트하기 전에 뭔가를 팔려고 하지 않았다는 것이 좋았습니다.

API 키 받기

가입 후, 저는 개발자 섹션으로 이동하여 키를 생성했습니다. 저는 테스트 프로젝트에 대해 레이블을 붙이고 로컬 .env 파일에 저장했습니다. 한 가지 작은 주의: 나중에 스테이징을 위해 두 번째 키를 만들었습니다. 환경별로 키를 범위 지정하면 어떤 호출이 제 유료 플랜을 적중시키는지 추측하는 것을 피할 수 있었습니다.

API 기본사항

엔드포인트 URL 구조

저는 대부분의 경우 단일 생성 엔드포인트를 사용했습니다. 패턴은 다음과 같았습니다:

  • 기본: api.wavespeed.ai
  • 버전 경로: /v1
  • 제품 경로: /z-image-turbo
  • 작업: /generate

따라서 일반적인 URL은 /v1/z-image-turbo/generate처럼 보였습니다. 버전이 변경되므로 버전을 하드코딩하지 않습니다. 기본과 버전을 구성에 넣어서 나중에 호출을 다시 쓸 필요 없이 업데이트할 수 있습니다.

인증 헤더 설정

인증은 표준 Bearer 토큰이었습니다. 도움이 된 것은 헤더 설정을 중앙집중식으로 유지하는 것이었습니다:

  • Authorization: Bearer YOUR_API_KEY
  • Content-Type: application/json

저는 먼저 작은 타임아웃(10초)으로 테스트한 다음, 이를 늘렸습니다. 서비스가 로드 중일 때, 이미지 생성은 일반적인 REST 호출보다 오래 걸릴 수 있습니다. 적극적으로 재시도하고 속도 제한에 도달하는 것보다 미리 계획하는 것이 낫습니다.

핵심 매개변수 설명

prompt, 효과적인 프롬프트 작성

저는 프롬프트 시인이 아닙니다. 여기서 작동한 것은 단순하고 문자 그대로의 언어와 하나의 명확한 스타일 단서였습니다. 제품 사진의 경우, 안정적인 구조를 찾았습니다:

  • 주제: “흰색 매끄러운 배경에 무광 검정색 무선 이어버드”
  • 각도 또는 렌즈: “45도 각도, 부드러운 스튜디오 조명”
  • 컨텍스트 단서: “최소한의 그림자, 반사 없음”

저는 이미지가 표류했기 때문에 스타일을 쌓는 것(“시네마틱, 무드, 에디토리얼, 광택”)을 피했습니다. 짧고 평이한 프롬프트가 더 예측 가능한 결과를 주었습니다.

두 번의 통과가 저를 반복하는 데 도움이 되었습니다:

  • 첫 번째 통과: 구성을 보기 위한 광범위한 프롬프트.
  • 두 번째 통과: 필요한 경우에만 제약을 추가합니다 (그림자 길이, 배경 텍스처).

size, 지원되는 해상도 (256-1536)

저는 대부분 정사각형과 세로 크기를 사용했습니다. API는 256부터 1536까지의 일반적인 값을 수용했습니다. 저는 빠른 미리보기를 위해 512에, 최종 자산을 위해 1024에 고집했습니다. 1536은 좋은 세부 사항을 생성했지만 더 많은 시간과 토큰이 비용이 들었습니다. 많은 변형을 생성하는 경우, 작은 크기로 시작하여 선택된 프롬프트를 더 높은 크기로 업스케일하거나 다시 실행합니다.

seed, 재현성 제어

Seed는 제가 예상한 것보다 더 중요했습니다. 마음에 드는 모습을 찾으면, 배경 밀도와 같은 변수 하나만 조정할 수 있도록 seed를 저장했고 너무 멀어지지 않도록 했습니다. 프롬프트를 많이 변경한 경우, 모델의 이전 편견과 싸우는 것을 피하기 위해 seed를 지웠습니다. 실제로는: 이미지 ID당 프롬프트, 크기 및 seed를 기록했습니다. 이것이 재렌더링을 지루하게 만들었고, 좋은 방식으로요.

output_format, JPEG 대 PNG 대 WebP

  • JPEG: 가볍고 빠릅니다. 미리보기 및 투명도가 없는 웹 자산에 좋습니다.
  • PNG: ​무손실, 더 큼. UI 오버레이나 깨끗한 가장자리가 필요할 때 사용했습니다.
  • WebP: ​좋은 중간 지점. PNG보다 작고, 공격적인 JPEG보다 깨끗합니다.

일괄 처리할 때, 미리보기를 JPEG로, 최종본을 대상에 따라 PNG 또는 WebP로 설정했습니다. 한 번에 혼합 형식을 섞는 것은 가능하지만, 일괄 처리당 일관성을 유지하여 북키핑을 줄였습니다.

코드 예제

cURL 빠른 시작여기는 엔드포인트를 제정신으로 확인하는 데 사용한 가장 짧은 경로입니다. cURL로 시작하는 것을 좋아하는 이유는 오류 메시지가 명확하기 때문입니다.

Bash

curl -X POST https://api.wavespeed.ai/v1/z-image-turbo/generate \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a matte black wireless earbud on a white seamless background, soft studio lighting",
    "size": 1024,
    "seed": 12345,
    "output_format": "webp",
    "enable_sync_mode": true
  }' \
  --output preview.webp

동기 모드가 활성화되고 요청에 지원되면, 응답은 이진 이미지 데이터 또는 base64 필드를 반환합니다(헤더 및 서버 설정에 따라 다름). 테스트 중에 파일에 직접 저장했습니다.

Python 구현Python 버전을 단순하게 유지했습니다. 요청, 타임아웃, 기본 오류 검사.

Python

import os
import requests
import base64

API_KEY = os.getenv("WAVESPEED_API_KEY")
URL = "https://api.wavespeed.ai/v1/z-image-turbo/generate"

payload = {
    "prompt": "cozy reading nook by a window, soft morning light, minimalist",
    "size": 1024,
    "output_format": "png",
    "enable_sync_mode": True,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()

# Some deployments return JSON with base64. Others return binary directly.
content_type = resp.headers.get("Content-Type", "")
if "application/json" in content_type:
    data = resp.json()
    img_b64 = data.get("image_base64")
    if not img_b64:
        raise RuntimeError("No image in response")
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(img_b64))
else:
    with open("output.png", "wb") as f:
        f.write(resp.content)

print("Saved output.png")

JavaScript/Node.js 예제Node에서는 타임아웃을 위해 AbortController로 fetch를 선호합니다.

JavaScript

import fetch from 'node-fetch';
import { writeFileSync } from 'fs';

const API_KEY = process.env.WAVESPEED_API_KEY;
const URL = "https://api.wavespeed.ai/v1/z-image-turbo/generate";

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000);

const payload = {
  prompt: "abstract paper texture, soft fibers, off-white, subtle grain",
  size: 512,
  output_format: "jpeg",
  enable_sync_mode: true,
};

try {
  const resp = await fetch(URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
    signal: controller.signal,
  });

  if (!resp.ok) {
    throw new Error(`${resp.status} ${resp.statusText}`);
  }

  const buffer = Buffer.from(await resp.arrayBuffer());
  writeFileSync("out.jpg", buffer);
  console.log("Saved out.jpg");
} catch (err) {
  console.error("Request failed:", err.message);
} finally {
  clearTimeout(timeoutId);
}

비동기 대 동기 모드

enable_sync_mode 설명

enable_sync_mode가 참일 때, 작은 이미지(512–1024)는 종종 한 번에 도착했습니다. 미리보기와 일회성 작업에는 좋았습니다. 하지만 동기 모드는 무거운 로드 또는 더 큰 크기에서 타임아웃합니다. 그 경계에 도달했을 때, API는 이미지 대신 작업 ID를 반환했습니다.

결과 폴링

비동기는 연결하는 데 2초가 걸렸고, 그 이후로는 문제없었습니다. 흐름:

  • enable_sync_mode를 false로 설정하여 생성 요청을 POST합니다(또는 생략하세요).
  • JSON에서 job_id를 받습니다.
  • 지수 백오프로 1–2초마다 상태 엔드포인트를 폴링합니다.
  • 상태가 완료되면, 제공된 URL에서 이미지를 다운로드합니다.

저는 폴링을 ~30초로 제한한 후 정상적으로 실패했습니다. 프로덕션에서는 서비스에서 제공하는 경우 웹훅으로 전환할 것입니다. 폴링은 작동하지만 낭만적이지는 않습니다.

오류 처리

일반적인 오류 코드

테스트 중에 본 것:

  • 400: 잘못된 필드 (범위를 벗어난 크기, 알 수 없는 형식). 페이로드를 수정하세요.
  • 401: 누락되거나 유효하지 않은 Bearer 토큰. 헤더와 키 범위를 확인하세요.
  • 404: 잘못된 엔드포인트 경로 또는 작업을 찾을 수 없습니다 (보통 오타).
  • 429: 속도 제한. 물러나고 나중에 다시 시도하세요.
  • 500/503: 일시적인 서비스 문제. 지터로 재시도하세요.

저는 응답 본문을 기록했습니다. 크기나 seed가 거부되었을 때 도움이 되는 일반 언어 힌트를 포함하는 경우가 많았기 때문입니다.

속도 제한 모범 사례

저는 짧은 큐가 있는 클라이언트에서 토큰 버킷을 사용했습니다. API가 429를 반환하면, 저는 지수 백오프를 하고 무작위 지터(50–200ms)를 추가하여 우레 같은 무리를 피했습니다. 또한 배치 요청(아래 참조)은 피크 버스트를 줄였습니다.

프로덕션 팁

일괄 처리 패턴

요청당 하나의 이미지를 생성하는 것은 단순했지만, 오버헤드가 낭비되었습니다. 작은 배치 크기(3–5개 프롬프트 각각)로 이동하고 더 안정적인 처리량을 얻었습니다. 저는 결과를 날짜 폴더에 작성하고 프롬프트, 크기, seed 및 출력 경로를 저장한 manifest.json 파일을 작성했습니다. 이 manifest는 이해당사자가 “같은 것을 할 수 있지만 따뜻한 빛으로?”라고 말했을 때 도움이 되었습니다. 저는 seed를 늘리거나 프롬프트를 조정하고 다시 실행했습니다.

비용 최적화

세 가지 사항이 중요했습니다:

  • 크기 규율: 512에서 미리보기, 필요한 경우에만 1024에서 최종. 1536은 자르기가 무거운 사용의 경우에만.
  • 형식 적합: 미리보기용 JPEG: 대부분의 웹 빌드용 WebP: 투명도가 필수 불가결할 때 PNG.
  • 조기 중단: 첫 번째 프레임이 잘못 보였으면, 기다리는 대신 작업을 취소했습니다. 그것은 동전을 절약했습니다, 누적되었습니다.

하나 더 실용적인 주의: 저는 스크립트에서 일일 지출을 제한했습니다. 화려하지는 않지만, 그것은 저를 실행 불가능한 루프로부터 보호했습니다.

마지막 몇 가지 관찰. Z-Image-Turbo API는 마법처럼 느껴지지 않았습니다. 아마도 그것이 제가 그것을 좋아한 이유일 것입니다. 가드레일을 설정하면 안정적이었습니다: 재현성을 위한 고정 seed, 작은 배치, 보수적인 타임아웃. 동기 모드는 미리보기에 좋았습니다: 비동기는 다른 모든 것에 이해가 있었습니다. 이미 AI 도구에 빠져 있다면, 이것은 관심을 위해 외치지 않을 것입니다. 파이프라인에 조용히 앉아서 일을 할 것입니다.

저는 여전히 더 높은 해상도에서 시끄러운 프롬프트를 어떻게 처리하는지 궁금합니다. 이것은 다른 날의 테스트입니다.