hiapi에서 wan2.7-image-standard API 사용하는 방법: 텍스트-이미지 생성 및 참조 이미지 편집

wan2.7-image-standard는 通义万相 Wan 2.7 Image 모델의 스탠다드 등급입니다. 별도 페이지로 다룰 가치가 있는 이유는 다음과 같습니다: 하나의 모델 ID로 텍스트-이미지 생성과 참조 이미지 기반 이미지 편집을 동시에 지원하며, 최대 2K까지 지원하고, 고정 가격 이미지당 $0.0345로 과금됩니다——4K를 지원하는 Pro 등급보다 저렴합니다. 본 가이드는 바로 실행 가능한 요청, 정확한 입력 스키마(실제 온라인 API로 검증 완료), 참조 이미지 편집 경로, 그리고 프로덕션 환경에서 반드시 처리해야 할 경계 동작을 제공합니다.

아래 스키마와 오류 부분의 모든 내용은 작성 과정에서 실제 온라인 /v1/tasks 엔드포인트를 탐색하여 확인한 것입니다——열거형 목록, 허용되는 필드 집합, 실패 응답 형태는 모두 기억이 아닌 실제 API 응답에서 인용했습니다.

무엇을 만들고 무엇을 준비해야 하는가

프롬프트를 제출하고(선택적으로 참조 이미지 첨부), 작업이 완료될 때까지 폴링한 다음 이미지를 다운로드합니다. 먼저 한 가지가 필요합니다: hiapi 빠른 시작에서 API 키를 받아 HIAPI_API_KEY로 내보내세요. 키 없는 경로는 없습니다——모든 요청은 Authorization: Bearer sk-<your-key>로 인증됩니다.

wan2.7-image-standard는 hiapi의 비동기 작업 API에서 실행됩니다: 먼저 POST /v1/tasks로 작업을 생성한 다음, 상세 엔드포인트를 폴링하여 종료 상태를 보고할 때까지 확인합니다.

텍스트-이미지 생성: 최소 요청

작업 생성:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "비 온 뒤 블루 아워, 조용하고 인적 없는 골목에 작은 도예 공방이 있고, 따뜻한 종이 랜턴이 걸려 있으며, 진열창에 유약을 입힌 찻주전자가 놓여 있고, 젖은 석판길에 불빛이 반사되며, 벽에 자전거 한 대가 기대어 있는, 시네마틱 35mm 사진, 고디테일",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

응답의 작업 id는 data.taskId에 있습니다:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D5..." }, "message": "success" }

그런 다음 GET /v1/tasks/<taskId>를 data.status가 success가 될 때까지 폴링하고, data.output[0].url에서 이미지 URL을 읽습니다:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="16:9", resolution="2K", image_urls=None, timeout=600):
    payload = {"model": "wan2.7-image-standard",
               "input": {"prompt": prompt,
                         "aspect_ratio": aspect_ratio,
                         "resolution": resolution}}
    if image_urls:                      # 참조 이미지 편집(다음 섹션 참조)
        payload["input"]["image_urls"] = image_urls

    create = requests.post(API, headers=HEADERS, json=payload).json()
    if create.get("code") != 200:       # 동기 검증 오류(예: 잘못된 열거형 값)
        raise RuntimeError(create)
    task_id = create["data"]["taskId"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if data["status"] == "success":
            return requests.get(data["output"][0]["url"]).content
        if data["status"] == "fail":    # 종료 상태 실패——폴링을 계속하지 말 것
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...")   # 바이트를 즉시 저장——아래 만료 설명 참조

aspect_ratio와 resolution은 모두 선택 사항입니다(모델에 기본값이 있음). 하지만 명시적으로 설정하세요——resolution은 1K 또는 2K만 허용되며, 둘 다 과금이 동일하므로 기본값으로 두는 것은 비용상 아무 이점이 없습니다.

참조 이미지 기반 편집: 동일한 모델 ID에 image_urls 추가

여기가 스탠다드 등급과 Pro 등급의 차이점입니다. image_urls에 참조 이미지를 전달하면(모델 사양에 따라 최대 9장), 모델이 이를 기반으로 편집하거나 재구성하면서도 텍스트 프롬프트를 계속 따릅니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "이 제품을 햇빛이 잘 드는 대리석 주방 조리대 위에 놓고, 옆에 신선한 허브를 두고, 이른 아침의 부드러운 빛, 라이프스타일 제품 사진",
      "image_urls": ["https://your-storage.example.com/product.jpg"],
      "resolution": "2K"
    }
  }'

Python에서는 위 도우미 함수에 image_urls=[...] 매개변수를 전달하면 됩니다——다른 것은 변하지 않습니다. 참조 이미지를 전달하더라도 prompt는 여전히 필수입니다(API는 prompt 없는 요청을 거부합니다: missing required field "prompt").

필드 이름이 중요합니다: image_urls입니다. 그럴듯해 보이는 대체 이름——reference_image_urls, image_input, input_urls——은 모두 스키마에 의해 additional properties '<name>' not allowed로 거부됩니다. 다른 모델의 편집 엔드포인트에서 코드를 포팅하는 경우라면 이것이 가장 먼저 수정할 부분입니다.

정확한 입력 스키마

스키마는 엄격합니다: 아래 목록에 없는 필드는 400 INVALID_REQUEST와 함께 additional properties '<name>' not allowed를 반환합니다. 다음은 허용되는 전체 필드입니다:

필드	유형	필수	설명
prompt	string	예	텍스트-이미지 생성과 편집 모두 필수. 영어 또는 중국어 사용 가능.
aspect_ratio	string enum	아니오	다음 중 하나: 1:1, 16:9, 4:3, 21:9, 3:4, 9:16, 8:1, 1:8. 다른 값(예: 3:2) → 400.
resolution	string enum	아니오	1K 또는 2K만 가능. 이 등급은 4K를 지원하지 않습니다.
image_urls	string[]	아니오	편집용 참조 이미지(최대 9장). 전달하면 참조 모드로 전환됩니다.
seed	integer	아니오	재현 가능한 출력을 위해 사용.

떠올릴 수 있지만 이 모델이 허용하지 않는 필드: negative_prompt, n, size, prompt_optimizer는 모두 알 수 없는 속성으로 거부됩니다. 배치(n) 매개변수는 없습니다——이미지마다 하나의 작업을 제출하세요.

프로덕션 주의사항 및 실측 동작

제출 시 200이 반환된다고 해서 이미지가 반드시 생성되는 것은 아닙니다. wan2.7-image-standard는 열거형 값을 동기적으로 검증합니다(잘못된 resolution 또는 aspect_ratio는 POST를 즉시 400 INVALID_REQUEST로 실패시킴). 하지만 제출 시 참조 URL은 검증하지 않습니다. 형식이 잘못되었거나 접근 불가능한 image_urls 항목은 허용되어 200과 taskId를 반환하고, 그런 다음 작업이 약 1초 후 실패합니다. 이를 직접 검증했습니다: 유효하지 않은 참조 URL로 생성한 작업은 다음과 같은 종료 상태를 반환했습니다

{ "status": "fail", "error": { "code": "INVALID_REQUEST", "message": "invalid request parameters for this model" } }

실제 결과는 다음과 같습니다: 항상 종료 상태까지 폴링하고, data.status == "fail" 분기로 처리해야 합니다(data.error 읽기). 실패한 작업은 HTTP 200 및 data.status: "fail"로 보고됩니다——실패 정보는 최상위 HTTP 오류가 아니라 data.error에 있습니다. 제출 전에 참조 URL이 공개적으로 접근 가능한지 확인하세요.

출력을 즉시 다운로드하세요. data.output[0].url은 expireAt 타임스탬프가 있는 임시 링크이며, 영구 CDN 리소스가 아닙니다. 작업이 성공하는 순간 바이트 내용을 가져와 자체 스토리지로 옮기세요; 만료된 URL은 404를 반환합니다. 이미 이 문제를 겪었다면 hiapi 출력 URL이 404가 되는 이유와 대처 방법을 참조하세요.

폴링 vs. 콜백. 위 예제는 5초마다 폴링하며, 이는 스크립트와 소규모 배치에는 괜찮습니다. 프로덕션 처리량을 위해서는 생성 요청에 callback을 추가하여 연결을 유지하는 대신 hiapi가 종료 이벤트 시 알려주도록 하세요——구체적인 메커니즘은 작업 생성 문서를 참조하세요.

스탠다드 vs. Pro: 어느 등급을 호출해야 하는가

hiapi는 두 개의 Wan 2.7 Image 등급을 호스팅하며, 이들은 매개변수가 아닌 서로 다른 모델 ID입니다:

• wan2.7-image-standard(본 가이드)——텍스트-이미지 생성 및 참조 이미지 편집, 1K/2K, 어떤 해상도든 고정 가격 이미지당 $0.0345로 과금.
• wan2.7-image/text-to-image——Pro 등급: 텍스트-이미지 생성만, 최대 4K, 고정 가격 이미지당 $0.08. Wan 2.7 Image Pro 페이지 및 이를 사용한 4K 이커머스 제품 이미지 생성 상세 설명을 참조하세요.

참조 이미지 기반 편집이 필요하거나 2K로 충분하며 Pro 이미지당 가격의 절반 미만을 지불하고 싶을 때 스탠다드 등급을 선택하세요. 네이티브 4K 출력이 특히 필요할 때만 Pro를 사용하세요——이것이 스탠다드 등급이 할 수 없는 유일한 일입니다. 두 모델의 현재 가격은 가격 페이지를 참조하세요.

자주 묻는 질문

wan2.7-image-standard는 이미지 편집을 지원하나요, 아니면 텍스트-이미지 생성만 지원하나요? 둘 다 지원하며, 동일한 모델 ID에서 가능합니다. image_urls 배열을 추가하면 참조 이미지 기반 편집으로 전환되고, 생략하면 순수 텍스트-이미지 생성입니다.

최대 해상도는 얼마인가요? 2K입니다. resolution 필드는 1K와 2K만 허용하며, 온라인 API는 다른 값을 거부합니다. 4K가 필요하면 Pro 등급(wan2.7-image/text-to-image)을 사용하세요.

작업이 200을 반환한 후 왜 실패했나요? 참조 URL은 제출 시 검사되지 않으며 실행 시에만 검사됩니다. 접근 불가능하거나 형식이 잘못된 image_urls 항목은 작업을 생성하고(HTTP 200) INVALID_REQUEST 종료 상태로 실패합니다. data.status를 폴링하고 URL이 공개적으로 접근 가능한지 확인하세요.

부정 프롬프트를 설정할 수 있나요? 아닙니다. negative_prompt는 이 모델이 허용하는 필드가 아닙니다(n, size, prompt_optimizer도 마찬가지). 긍정 prompt와 seed로 유도하세요.