HiAPI
블로그

튜토리얼

HiAPI API로 qwen-image-2.0-pro를 사용하는 방법: curl, Python 및 바로 통하는 요청

개발자를 위한 실전 통합 워크스루: 첫 성공 호출, 요청 구조 분석, 문제 진단

Nov 17, 2026
미니멀한 종이 레이어 중첩 커버 이미지: 크림색 바탕 위에 여러 겹의 그라파이트색 얇은 종이가 차례로 어긋나며 얕은 심도로 물러나고, 중앙에 테라코타색 종이 한 장이 포인트를 준다.
이 페이지에서

qwen-image-2.0-pro가 API 사용자에게 제공하는 것

qwen-image-2.0-pro는 HTTP로 호출하는 이미지 생성 모델입니다. 코드 관점에서 보면 채팅 완성 엔드포인트와 유사하게 동작합니다. 원하는 이미지를 설명하는 JSON 페이로드를 보내면 생성된 이미지가 포함된 JSON 응답을 받습니다.

HiAPI API를 통해 접근할 때의 장점은 일관성입니다. 하나의 API 키, 하나의 기본 URL, 하나의 요청 구조로 모델 전반에 걸쳐 공통으로 사용할 수 있습니다. 나중에 모델 식별자를 바꾸거나 파라미터를 조정해도 주변 코드는 그대로 유지됩니다. 시도하는 모든 이미지 모델마다 새로운 SDK를 익히거나 여러 자격 증명을 관리할 필요가 없습니다.

이 튜토리얼에서는 먼저 curl로 첫 호출을 완전히 완료한 뒤 Python으로 옮기고, 응답에서 이미지를 읽는 방법을 설명한 다음, 진단 체크리스트와 작은 재사용 래퍼를 제시합니다. 모든 예제는 동일한 페이로드와 동일한 키 환경 변수를 사용하므로, 터미널에서 동작한 내용이 스크립트에서도 수정 없이 실행됩니다.

사전 준비와 키 설정

코드를 작성하기 전에 다음 세 가지가 준비되어 있는지 확인하세요.

1. HiAPI 계정과 API 키

계정을 만들고 대시보드에서 API 키를 생성하세요. 키는 기밀 정보이므로 비밀번호처럼 다루어야 합니다. 버전 관리에 커밋될 소스 파일에 붙여넣지 마세요.

2. 키를 환경 변수로 내보내기

다음 예제는 HIAPI_API_KEY에서 키를 읽으므로 동일한 명령과 스크립트가 로컬과 CI에서 수정 없이 실행됩니다.

export HIAPI_API_KEY="your_key_here"

Windows PowerShell에서는 $env:HIAPI_API_KEY = "your_key_here"를 사용하세요. CI에서는 파이프라인 구성의 비밀 환경 변수로 설정하세요.

3. HTTP 요청을 보낼 도구

curl은 보통 미리 설치되어 있습니다. Python의 경우 Python 3와 requests 라이브러리가 필요합니다:

pip install requests

계속하기 전에 셸에서 키가 보이는지 확인할 수 있습니다:

# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."

출력이 없다면 해당 변수가 설정되지 않은 것이며, 모든 요청이 인증 오류로 실패합니다. 먼저 이 문제를 해결하세요.

curl로 보내는 최소 동작 요청

연결성을 가장 빠르게 확인하는 방법은 환경 변수에서 키를 읽어 curl 호출을 실행하는 것입니다. 페이로드는 model 필드와 채팅 완성 스타일의 messages 배열을 포함하는 JSON 객체입니다.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0-pro",
    "messages": [
      {
        "role": "user",
        "content": "A small ceramic mug on a wooden table, soft morning light, product photo"
      }
    ]
  }'

여기서 세 가지 세부 사항이 중요합니다. Authorization 헤더는 Bearer 방식을 사용합니다. model 값은 모델 식별자와 정확히 일치해야 합니다. content는 이미지를 설명하는 순수 문자열 프롬프트입니다.

요청이 성공하면 터미널에 JSON 응답이 출력됩니다. 실패하면 HTTP 상태 코드와 오류 메시지가 표시됩니다. 응답 본문을 읽기 전에 상태 코드를 먼저 확인하세요. 401은 키가 잘못되었거나 누락된 경우, 400은 보통 페이로드 형식 오류, 404 또는 모델을 찾을 수 없다는 오류는 모델 식별자가 잘못된 경우입니다.

이 명령이 성공 응답을 반환하면 연결성이 정상임이 확인된 것이므로 코드 작성으로 넘어갈 수 있습니다.

Python에서의 동일한 요청

호출을 Python으로 옮길 때 페이로드는 완전히 동일하게 유지하세요. 유일한 차이는 환경 변수를 읽고 요청을 직렬화하는 방식입니다.

import json
import os

import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "qwen-image-2.0-pro",
    "messages": [
        {
            "role": "user",
            "content": "A small ceramic mug on a wooden table, soft morning light, product photo",
        }
    ],
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))

json=payload는 requests가 Content-Type 헤더를 자동으로 설정하고 요청 본문을 직렬화하게 합니다. timeout은 중요합니다. 이미지 생성은 일반적인 텍스트 완성보다 오래 걸릴 수 있으므로 120초는 합리적인 출발점입니다. raise_for_status()는 오류 상태 코드를 예외로 변환하므로 실패가 조용히 넘어가지 않습니다.

이 스크립트를 실행하면 curl에서 본 것과 동일한 JSON을 얻어야 합니다. 그렇지 않다면 curl이 성공한 셸과 환경이 다르다는 뜻이며, 가장 흔한 원인은 키 변수입니다.

응답 읽기와 이미지 출력 처리

응답은 채팅 완성 구조를 따르므로 생성된 이미지는 텍스트 응답을 처리하는 것과 동일한 경로로 가져옵니다. 먼저 출력된 JSON을 확인하세요. 구조는 익숙할 것입니다:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      }
    }
  ]
}

생성된 이미지는 어시스턴트 메시지 콘텐츠에 나타나며, 모델이 미디어를 반환하는 방식에 따라 보통 URL 또는 base64 인코딩 페이로드로 표시됩니다. 어느 쪽인지 가정하지 말고, 값을 읽은 뒤 접두사에 따라 분기 처리하세요:

content = data["choices"][0]["message"]["content"]

if isinstance(content, str) and content.startswith("http"):
    image_url = content
    # Download and save if you want a local copy
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print("saved output.png from URL")
else:
    # Treat as base64-encoded image data
    import base64

    image_bytes = base64.b64decode(content)
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print("saved output.png from base64")

실용적인 설명 두 가지. 콘텐츠가 URL이라면 임시 링크로 취급하고 제품에서 직접 링크하지 말고 가능한 한 빨리 다운로드하세요. base64라면 디코딩 과정을 격리하여 형식이 잘못된 페이로드가 잡을 수 있는 오류를 던지도록 하세요. 파싱 전에 항상 원본 응답을 로그 파일에 기록해 두면 느릴 수 있는 요청을 다시 실행하지 않고도 디버깅할 수 있습니다.

실패한 요청에 대한 진단 체크리스트

요청이 실패할 때 전체 호출을 서둘러 다시 작성하지 마세요. 다음 검사를 순서대로 수행하고 첫 번째 실패 지점에서 멈추세요. 각 검사는 하나의 변수를 격리합니다.

1. 인증

먼저 상태 코드를 확인하세요. 401은 키가 누락되었거나 만료되었거나 형식이 잘못된 경우입니다. 현재 셸에 해당 환경 변수가 설정되어 있는지, Bearer 접두사를 사용했는지, 헤더에 후행 공백이 없는지 확인하세요.

2. 모델 식별자

모델을 찾을 수 없다는 오류는 model 값이 사용 가능한 모델과 정확히 일치하지 않음을 의미합니다. 대소문자와 접미사가 모두 중요합니다. 값을 모델 문서 페이지와 문자 단위로 비교하세요.

3. 페이로드 구조

400은 보통 형식이 잘못된 요청 본문에서 발생합니다. messages가 배열인지, 각 메시지에 role과 content가 포함되어 있는지, JSON이 유효한지 확인하세요. 전송 전에 jq 또는 python -m json.tool로 페이로드를 처리하면 구문 오류를 잡을 수 있습니다.

4. 응답 처리

요청은 성공했지만 스크립트가 충돌한다면 문제는 API가 아니라 파싱 코드에 있습니다. 슬라이싱 전에 원본 응답 본문을 기록하고, 읽는 경로가 실제로 존재하는지 확인하세요. 이미지는 한 호출에서는 URL로, 다른 호출에서는 base64로 반환될 수 있으므로 가정하지 말고 콘텐츠에 따라 분기 처리하세요.

5. 시간 초과와 재시도

이미지 생성은 느릴 수 있습니다. 시간 초과가 발생하면 클라이언트 시간 초과를 늘리고 한 번 재시도하세요. 4xx 오류는 같은 방식으로 다시 실패하므로 재시도하지 마세요.

유용한 습관: 알려진 정상 요청의 사본을 저장하고 실패한 요청과 비교하세요. 대부분의 실패는 필드 하나 차이입니다.

재사용 가능한 클라이언트로 래핑하기

호출이 성공하면 작은 함수 뒤로 래핑하여 모델과 파라미터 변경이 한 곳에 모이도록 하세요. 이 래퍼는 키 조회, 요청 헤더, 오류 처리를 중앙에서 관리합니다:

import base64
import os

import requests

HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"


def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
    """Generate an image and return its raw bytes."""
    api_key = os.environ["HIAPI_API_KEY"]
    payload = {
        "model": model,
        "messages": [{"role": "user", "content": prompt}],
    }
    response = requests.post(
        f"{HIAPI_BASE}/chat/completions",
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    content = response.json()["choices"][0]["message"]["content"]

    if isinstance(content, str) and content.startswith("http"):
        return requests.get(content, timeout=60).content
    return base64.b64decode(content)

호출 코드는 한 줄이 됩니다: open("out.png", "wb").write(generate_image("A ceramic mug on a wooden table")). 나중에 다른 이미지 모델로 전환하거나 파라미터를 추가하려면 이 함수만 수정하면 됩니다. 모델 식별자와 모든 파라미터 세부 사항은 모델 페이지에 있으므로, 연동하기 전에 qwen-image-2.0-pro 모델 상세를 먼저 확인할 수 있습니다.

curl 호출로 시작하고, 다음으로 Python 스크립트, 마지막으로 래핑으로 진행하세요. 각 단계는 다음 계층을 구축하기 전에 더 작은 부분을 확인합니다.

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

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

API 문서 보기