블로그

튜토리얼

HiAPI API로 qwen-image-3.0-pro/image-to-image를 호출하는 방법: curl, Python 그리고 실제로 동작하는 요청 한 번

비동기 작업 패턴, curl 및 Python 클라이언트, 오류 처리를 다루는 통합 실습

Nov 10, 2026
커버 이미지: 어긋나게 겹쳐진 종이들이 마치 인쇄가 어긋난 인쇄물처럼 보이며, 아이보리색 종이 표면에 차콜 블랙 가장자리와 한 장의 녹슨 빨강 삽지가 있고, 오른쪽 아래에 평평한 그림자가 드리워져 있다.
이 페이지에서

이미지 생성(image-to-image)이 비동기 작업인 이유

이미지 생성 모델을 호출할 때, 당신이 요청하는 것은 수백 밀리초 안에 스트리밍으로 반환되는 문자열 완성 결과가 아닙니다. 모델은 소스 이미지를 불러와 그것을 조건으로 전체 확산 기반 생성 과정을 실행하고 출력을 인코딩해야 합니다. 이는 해상도와 설정에 따라 수 초에서 수십 초까지 걸릴 수 있습니다. 그 전체 구간 동안 HTTP 연결을 열어두는 것은 어느 쪽에도 이득이 없습니다. 프록시는 타임아웃되고, 로드 밸런서는 유휴 소켓을 버리며, 당신의 작업 스레드도 나중에 실패할지도 모르는 요청 하나에 묶여 있게 됩니다.

그래서 이 엔드포인트는 '먼저 제출하고, 나중에 폴링'하는 모델을 사용합니다. 첫 번째 요청이 작업을 제출하고 즉시 작업 핸들을 반환합니다. 이미지 생성은 그 핸들 뒤에서 진행됩니다. 이후 당신은 작업 상태를 확인하기 위해 독립적이고 오버헤드가 낮은 요청을 보내며, 완료를 보고할 때까지 반복합니다. 그 시점에 응답은 당신이 요청한 결과를 담고 있습니다.

여기에는 처음부터 설계에 반영해야 할 실질적인 결과가 따릅니다.

  • 제출은 완료가 아닙니다. 제출 호출이 성공했다는 것은 플랫폼이 당신의 작업을 접수했다는 것일 뿐, 그 이상도 이하도 아닙니다. 코드에서 이 두 상태를 구분하세요.
  • 작업 ID가 당신의 유일한 핸들입니다. 반드시 영속적으로 저장하세요. 프로세스가 제출과 폴링 사이에 죽더라도, 작업 ID가 있으면 같은 작업을 다시 제출(그리고 다시 결제)하지 않고 복구할 수 있습니다.
  • 폴링은 오버헤드가 낮지만 공짜는 아닙니다. 상태 확인은 가볍지만, 촘촘한 루프는 여전히 트래픽을 발생시키고 속도 제한을 유발할 수 있습니다. 간격을 두세요.
  • 실패는 비동기적으로 도착합니다. 손상된 이미지나 거부된 파라미터는 제출 시점의 HTTP 오류가 아니라 작업 수준의 오류로 나타날 수 있습니다. 폴링 코드는 상태 코드만이 아니라 작업 상태를 읽어야 합니다.

이 모델을 기억하면 이후 통합은 곧바로 진행됩니다. 한 번의 호출로 작업을 만들고, 하나의 루프로 그것을 기다리며, 잘못될 수 있는 세 가지 상황을 의도적으로 처리하면 됩니다.

코드를 쓰기 전에: 무엇을 준비해야 하는가

터미널을 열기 전에, 이 가이드의 모든 호출이 의존하는 몇 가지를 먼저 모으세요.

HiAPI 자격 증명

HiAPI의 API 키가 필요합니다. 비밀로 취급하세요. 제출할지도 모르는 스크립트에 붙여 넣지 말고 환경 변수에서 불러오세요. 아래 예제는 이를 HIAPI_API_KEY로 읽습니다. API의 기본 URL과 정확한 모델 식별자 qwen-image-3.0-pro/image-to-image는 전 과정에서 참조할 두 개의 상수입니다.

소스 이미지 한 장

이미지 생성에는 입력이 필요합니다. 한 장을 준비하고 어떻게 제공할지 정하세요.

  • 공개적으로 접근 가능한 URL로, 또는
  • 업로드된 자산이나 인코딩된 페이로드로, 엔드포인트가 받아들이는 형식에 따라.

호출을 작성하기 전에 모델의 요청 스키마를 확인해 정확한 필드 이름과 허용되는 소스 이미지 형식을 확정하세요. 엔드포인트가 받아들이지 않는 소스 이미지를 제공하는 것은 작업이 거부되는 가장 흔한 원인이며, 오류 메시지에서 디버깅하는 것보다 미리 배제하는 편이 훨씬 쉽습니다.

폴링할 수 있는 클라이언트

호출이 비동기이므로, 요청을 보내는 도구도 후속 요청을 반복해서 보낼 수 있어야 합니다. curl은 첫 스모크 테스트에 적합하고, 그보다 장기적인 용도는 모두 스크립트여야 합니다. 설정할 콜백 URL도, 호스팅할 웹훅도 없습니다. 폴링이 바로 메커니즘이므로 루프를 계획하세요.

결과를 확인할 곳

당신에게 '완료'가 어떤 모습인지 미리 정하세요. 브라우저에서 열 수 있는 URL이거나 디스크에 쓰는 바이트입니다. 시작 전에 이것을 알고 있으면, 통합이 실제로 동작하는 순간을 한눈에 알 수 있습니다.

이 네 가지가 준비되면 첫 요청은 짧아집니다.

curl로 동작하는 요청 한 번 보내기

키, 엔드포인트, 작업 생명주기가 모두 동작하는지 확인하는 가장 빠른 방법은 두 단계짜리 curl 세션입니다. 먼저 제출하고, 그다음 폴링합니다.

1단계: 작업 제출

curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/source.jpg",
    "prompt": "restyle as a soft watercolor illustration"
  }'

항목별 설명:

  • -X POST —— 제출은 생성 작업입니다.
  • Authorization 헤더가 당신의 키를 담습니다. 인라인으로 입력하는 대신 환경 변수로 내보내면 셸 기록에 남지 않습니다.
  • Content-Type: application/json —— 요청 본문은 JSON입니다.
  • -d —— JSON 페이로드입니다. image 필드는 소스 이미지를 가리키고, prompt는 수행할 변환을 설명합니다. 파라미터 이름과 허용되는 옵션은 모델의 요청 스키마에서 비롯되므로, 추측하지 말고 그곳에서 확인하세요.

제출 성공 응답은 작업 객체입니다. 여기에는 식별자(작업 ID라고 부릅시다)와 작업이 대기 중이거나 실행 중임을 나타내는 상태 필드가 포함됩니다. 작업 ID를 기록하세요. 이후의 모든 것이 여기에 의존합니다.

2단계: 작업 폴링

export TASK_ID="<the id from the submit response>"

curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

매 호출마다 상태 필드를 읽으세요. 대기 중이나 실행 중 상태를 보고하면 몇 초 기다렸다가 다시 확인하세요. 성공을 보고하면 응답에 생성된 이미지가 포함됩니다. 보통 가져올 수 있는 URL이거나 인코딩된 데이터입니다. 실패를 보고하면 응답에 이유를 설명하는 오류 설명이 담깁니다.

생명주기 전체가 이렇습니다. 한 번 제출하고, 최종 상태까지 상태를 확인합니다. 이후 당신이 만드는 모든 것은 이 두 명령의 더 편리한 버전에 대기와 오류 처리를 더한 것일 뿐입니다.

Python으로 동일한 호출 구현하기

이 두 curl 단계를 수동으로 반복하는 것은 금방 지루해지고, 폴링 루프를 모든 스크립트에 복사 붙여넣기하는 것은 미묘한 버그가 퍼지는 방식입니다. 제출과 폴링 패턴을 재사용 가능한 함수로 감싸세요.

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def submit_task(source_image: str, prompt: str) -> str:
    resp = requests.post(
        BASE_URL + MODEL_PATH,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": source_image, "prompt": prompt},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]


def wait_for_task(task_id: str, poll_interval: float = 3.0,
                  max_wait: float = 300.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        task = resp.json()
        status = task["status"]
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")


def generate(source_image: str, prompt: str) -> dict:
    task_id = submit_task(source_image, prompt)
    return wait_for_task(task_id)

몇 가지 의도적인 선택을 짚어볼 만합니다.

  • 제출과 대기의 분리. 제출이 실패하면 폴링이 일어나기 전에 알 수 있습니다. 나중에 한 프로세스에서 제출하고 다른 프로세스에서 수집하고 싶다면, 이음새가 이미 있습니다.
  • 모든 요청에 timeout이 있습니다. 타임아웃이 없는 요청은 무한정 매달릴 수 있으며, 이것이 바로 비동기 API가 막아주어야 할 실패 모드입니다.
  • 폴링 루프에 간격과 전체 마감 시간이 모두 있습니다. 마감 시간이 없으면 실행 중 상태에 갇힌 작업이 영원히 순환합니다. 간격이 없으면 엔드포인트를 마구 두드리게 됩니다.
  • 상태 문자열은 명시적으로 매칭됩니다. 성공도 실패도 아닌 상태는 다음 반복으로 넘어가며, 이는 중간 상태에 대한 올바른 기본 동작입니다.

여느 함수처럼 호출하세요: generate(source_url, "make the background a dusk cityscape"). 반환된 객체는 최종 상태 작업 페이로드이며, 여기서 이미지 참조를 추출합니다.

오류와 실패한 작업 처리하기

비동기 워크플로의 오류는 세 가지 범주로 나뉘며, 각각 다른 대응이 필요합니다.

요청 수준 거부

제출 호출에 대한 일반 HTTP 오류 응답입니다. 자격 증명 오류나 누락, 잘못된 JSON 형식, 지원되지 않는 파라미터, 접근할 수 없는 소스 이미지 등입니다. 작업이 존재하기 전에 도착합니다.

올바른 대응은 거의 항상 멈추고 메시지를 제시하는 것입니다. 형식이 잘못된 페이로드를 재시도하는 것은 할당량과 시간만 낭비합니다. 상태 코드와 응답 본문을 그대로 기록하세요. 유효성 검사 메시지는 보통 문제가 되는 필드를 지목합니다. 특별히 처리할 만한 두 가지 경우가 있습니다. 인증 실패는 구성 문제를 의미하므로 빠르고 크게 실패해야 합니다. 속도 제한 응답은 백오프 후 재시도할 수 있습니다.

작업 수준 실패

여기서는 제출이 성공했고 작업 ID도 존재하지만, 작업 자체가 실패했습니다. 폴링 응답이 실패 상태와 함께 오류를 보고합니다.

이 범주는 모델 자체의 문제를 포괄합니다. 소스 이미지가 디코딩되지만 사용할 수 없는 경우, 프롬프트가 거부된 경우, 생성이 내부 한도에 도달한 경우 등입니다. 이는 입력에 특정된 문제이므로 맹목적인 재시도는 보통 같은 실패를 재현합니다. 경우별로 판단하세요. 일시적인 내부 오류는 한 번 재시도할 가치가 있을 수 있지만, 거부된 소스 이미지는 결코 그렇지 않습니다. 지원 요청과 연계할 수 있도록 오류와 함께 작업 ID를 기록하세요.

끝나지 않는 폴링

제출이 성공하고 작업이 존재하며 폴링이 실행 중인데, 최종 상태가 영원히 도착하지 않습니다. 이것은 플랫폼이 반환한 오류가 아니라, 당신의 코드에 있는 가정이 만료되어야 하는 상황입니다.

Python 예제처럼 마감 시간으로 보호하세요. 마감 시간이 발동하면 폴링을 중단하세요. 반쯤 완료된 결과를 조용히 반환하지 말고, 명시적인 타임아웃 결과를 던지거나 반환해 호출자가 결정하게 하세요. 작업 ID는 보관하세요. 작업은 당신의 마감 시간 이후에도 완료될 수 있으며, 다시 제출하지 않고 나중에 수집하고 싶을 수 있습니다.

이 세 범주에 대한 실용적인 황금률은 작업 상태를 유일한 진실의 원천으로 보는 것입니다. HTTP 상태 코드는 요청이 접수되었는지 알려주고, 작업의 상태와 오류 필드는 작업이 성공했는지 알려줍니다. 둘 다 읽으면 실패는 신비로운 것이 아니라 진단 가능한 것이 됩니다.

프로덕션 코드로 감싸기

위의 함수는 동작하는 통합이지 완성된 서비스가 아닙니다. 실제 트래픽을 감당하기 전에 네 가지를 다듬어야 합니다.

도처의 타임아웃

제출, 폴링, 그리고 결과 이미지에 대한 후속 가져오기 등 모든 호출에 명시적인 연결 및 읽기 타임아웃을 설정하세요. 그런 다음 전체 작업 생명주기에 대한 마감 시간을 설정하세요. HTTP 계층의 타임아웃은 개별 요청을 보호하고, 작업 마감 시간은 전체 작업을 보호합니다.

분별 있는 재시도

안전하게 재시도할 수 있는 것만 재시도하세요. 폴링 중의 속도 제한과 일시적인 네트워크 오류는 해당됩니다. 거부된 페이로드는 해당되지 않습니다. 작업 수준 실패에서 재시도는 새 작업을 제출하는 것을 의미하며, 이는 상태 확인을 재시도하는 것과는 다르고 더 비싼 작업입니다. 의도적인 결정으로 다루고, 가능하면 상한을 두세요.

작업 ID를 포함한 로그

제출 시점과 이후의 모든 상태 전환 시점에 작업 ID를 시간 정보와 함께 기록하세요. 제출과 첫 최종 상태 사이의 간격은 일이 느리게 느껴질 때 실제로 필요하게 될 지표입니다. 사용자가 나쁜 결과를 보고할 때, 작업 ID는 일화를 추적 가능한 기록으로 바꾸는 열쇠입니다.

폴링을 요청 경로에서 떼어내기

함수가 웹 핸들러 안에서 실행된다면, 동기 폴링 루프는 전체 생성 시간 동안 요청을 열어둡니다. 이것이 바로 비동기 설계가 피하려는 문제입니다. 대신 핸들러에서는 제출하고, 작업 ID를 호출자에게 반환하며, 대기는 백그라운드 워커, 큐 또는 예약 작업에서 수행하세요. 그러면 클라이언트는 모델이 아니라 당신의 서비스를 폴링합니다.

이 순서대로 구축하면 통합은 '내 머신에서는 동작한다'에서 의지할 수 있는 무언가로 바뀝니다. 제출하고, 핸들을 영속화하고, 제한을 두고 기다리며, 희망이 아니라 작업 상태가 언제 멈출지 알려주게 하세요.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기