HiAPI
Ko
블로그

튜토리얼

HiAPI API로 muse-image-1.0/text-to-image를 호출하는 방법: curl과 Python

Nov 3, 2026
米色纸层沿对角逐层退远的抽象几何封面图，石墨色层边与一张陶土色纸片点缀，为 HiAPI 教程文章配图。

이 통합이 실제로 포함하는 것

HiAPI에서 텍스트-이미지 호출은 동기 HTTP 요청 하나입니다. 원하는 이미지를 설명하는 JSON 요청 본문을 보내면, 응답이 돌아올 때 생성된 이미지 데이터가 포함됩니다. 이 엔드포인트에는 관리해야 할 폴링 루프나 작업 큐가 없습니다. 요청 한 번, 응답 한 번입니다.

관련된 구성 요소는 매우 적습니다:

  • 당신의 API 키 — Authorization 헤더를 통해 요청을 인증합니다.
  • 엔드포인트 — HiAPI 기본 URL에서 muse-image-1.0/text-to-image의 고정 URL 경로입니다.
  • JSON 요청 본문 — 프롬프트와 모델이 허용하는 모든 선택적 매개변수를 담습니다.
  • 응답 페이로드 — 생성된 이미지 데이터를 반환하며, 이를 디코딩하거나 전달합니다.

이것이 전체 인터페이스입니다. 아래 장에서는 curl로 요청을 조각조각 구성한 뒤, Python으로 동일한 과정을 반복합니다. 이렇게 하면 복잡성을 더하기 전에 각 부분을 검증할 수 있습니다.

사전 요구 사항 및 인증

첫 요청을 보내기 전에 다음을 갖추었는지 확인하세요:

  1. API 키 — HiAPI 계정 대시보드에서 발급받습니다. 비밀번호처럼 취급하고, 절대 소스 코드 관리에 커밋하지 마세요.
  2. HTTP 클라이언트 — 테스트에는 curl이면 충분하고, 스크립트 버전은 Python 3.8+를 대상으로 합니다.
  3. HiAPI API 기본 URL — 대시보드 문서에서 키와 함께 찾을 수 있습니다.

인증은 Authorization 헤더에 Bearer 토큰을 사용합니다. muse-image-1.0/text-to-image로 가는 모든 요청에 필요합니다:

Authorization: Bearer $HIAPI_API_KEY

키는 스크립트에 하드코딩하지 말고 환경 변수에 저장하세요:

export HIAPI_API_KEY="your-key-here"

이 모델의 엔드포인트 경로는 /muse-image-1.0/text-to-image이며, 기본 URL 뒤에 붙습니다. 정확한 기본 URL은 HiAPI 대시보드에 기록되어 있습니다. 코드를 수정하지 않고도 환경을 전환할 수 있도록 이것도 환경 변수에 저장하세요:

export HIAPI_BASE_URL="https://api.hiapi.ai"   # confirm the current value in your dashboard

두 변수를 설정하면 요청을 보낼 준비가 됩니다.

작동하는 curl 요청

다음은 최소한의 muse-image-1.0/text-to-image 호출 예시입니다. 프롬프트를 보내고 원시 JSON 응답을 파일에 기록하여, 어떤 파싱 코드를 작성하기 전에 검사할 수 있게 합니다.

curl -sS -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a quiet harbor at dawn, soft fog, wide angle",
    "n": 1
  }' \
  -o response.json

요청 본문에 대해 몇 가지 유의할 점이 있습니다:

  • prompt는 필수 항목입니다. 모델이 렌더링하는 텍스트 설명입니다.
  • n은 선택 사항이며, 요청할 이미지 수를 제어합니다. 생략하면 기본값을 사용합니다.
  • HiAPI API 참조 문서에서 이 모델에 대해 확인한 매개변수만 포함하세요. 문서화되지 않은 필드를 추측하지 마세요. 알 수 없는 매개변수는 서버 검증에서 거부되거나 조용히 무시될 수 있습니다.

요청이 성공하면 response.json에 이미지 데이터가 포함됩니다. 실패하면 오류 응답 본문과 2xx가 아닌 상태 코드를 받습니다. 아래 오류 처리 장을 참고하세요.

전체 응답 본문을 출력하지 않고 HTTP 상태 코드를 확인할 수 있습니다:

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test"}'

Python으로 동일한 요청 구현하기

Python 버전은 requests를 사용하며 curl 호출과 정확히 동일합니다. 같은 엔드포인트, 같은 헤더, 같은 요청 본문입니다. 이를 재사용 가능한 함수로 추출하세요.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_image(prompt: str, n: int = 1) -> dict:
    url = f"{BASE_URL}/muse-image-1.0/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"prompt": prompt, "n": n}

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()  # raise on 4xx/5xx
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft fog, wide angle")
    print(result.keys())

두 가지 세부 사항을 기억할 가치가 있습니다:

  • timeout=60 — 명시적 타임아웃을 설정하세요. 이미지 생성은 일반적인 JSON API 호출보다 느립니다. 타임아웃이 없으면 연결이 정체될 때 프로세스가 무기한 멈출 수 있습니다.
  • raise_for_status() — HTTP 오류를 예외로 노출하여, 오류 응답 본문을 이미지로 조용히 파싱하는 일을 방지합니다.

이미 httpx나 aiohttp를 사용 중이라면 전환은 간단합니다. 같은 헤더, 같은 JSON 요청 본문입니다. 이 요청은 특정 HTTP 라이브러리에 의존하지 않습니다.

동기 응답 읽기

muse-image-1.0/text-to-image는 동기식이므로 이미지 데이터가 같은 응답에 도착합니다. 결과를 가져오기 위한 두 번째 호출이 필요 없습니다. 응답은 JSON이므로 파서를 작성하기 전에 구조를 한 번 검사하세요:

import json

result = generate_image("a quiet harbor at dawn")
print(json.dumps(result, indent=2)[:500])

이미지를 처리하는 방법은 응답이 담고 있는 내용에 따라 달라집니다:

응답에 base64 이미지 데이터가 포함된 경우

문자열을 디코딩하고 바이트를 파일에 씁니다:

import base64

b64 = result["data"][0]["b64_json"]   # field name: confirm against the API reference
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

응답에 URL이 포함된 경우

일반 GET으로 다운로드하세요. 해당 URL은 검색에 대해 이미 권한이 부여되어 있으므로, 제3자 호스트에 API 키를 첨부하지 마세요:

import requests

image_url = result["data"][0]["url"]   # field name: confirm against the API reference
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

정확한 필드 이름(즉 b64_json과 url, 그리고 이를 감싸는 외부 구조)은 이 모델의 HiAPI API 참조 문서에 정의되어 있습니다. 응답을 한 번 출력하여 구조를 확인한 후, 그에 맞춰 코드를 작성하세요. 모델마다 구조가 다르다고 가정하지 마세요.

서비스에서는 로컬 디스크에 무작정 쓰지 마세요. 바이트를 객체 스토리지로 스트리밍하거나, 이미지를 소비하는 곳(업로드 단계, 큐, 자체 클라이언트로의 응답)으로 직접 전달하세요. 전달하기 전에 디코딩된 바이트가 이미지처럼 보이는지(매직 넘버 바이트 확인) 검증하세요.

오류 코드 처리 및 재시도

HiAPI는 표준 HTTP 상태 코드를 반환합니다. 유용한 분류 규칙은 다음과 같습니다: 요청을 바꾸지 않고 다시 보내면 같은 요청이 성공할 수 있는가?

요청 수정 — 재시도하지 않음

  • 400 Bad Request — 잘못된 형식의 JSON 또는 모델이 허용하지 않는 매개변수입니다. prompt가 존재하는지, 문서에 없는 필드를 만들어 넣지 않았는지 확인하세요. 요청 본문을 수정하세요. 그대로 재시도하면 똑같이 실패합니다.
  • 401 Unauthorized — API 키가 없거나 유효하지 않습니다. HIAPI_API_KEY가 설정되어 있고 교체되지 않았는지 확인하세요.
  • 403 Forbidden — 키는 유효하지만 이 엔드포인트에 접근할 권한이 없습니다. 대시보드에서 계정 접근 권한을 확인하세요.
  • 404 Not Found — 경로가 잘못되었습니다. 엔드포인트 문자열이 정확히 /muse-image-1.0/text-to-image인지, 기본 URL이 올바른지 확인하세요.
  • 422 Unprocessable Entity — JSON 형식은 올바르지만 의미상 유효하지 않습니다. 예를 들어 값이 범위를 벗어난 경우입니다. 오류 메시지를 읽으세요. 보통 어떤 필드인지 알려줍니다.

백오프를 동반한 재시도

  • 429 Too Many Requests — 속도 제한을 받고 있습니다. 지수 백오프 후 재시도하세요. Retry-After 헤더가 있으면 이를 준수하세요.
  • 5xx 오류 — 서버 측 장애입니다. 지수 백오프와 상한(예: 세 번 시도)을 사용해 재시도한 뒤, 포기하고 오류를 노출하세요.

간결한 재시도 루프:

import time

def post_with_retry(url, headers, payload, attempts=3):
    for i in range(attempts):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"failed after {attempts} attempts: {resp.status_code} {resp.text}")

실패 시 항상 상태 코드와 오류 응답 본문을 기록하세요. 응답 본문의 메시지가 해당 오류가 두 범주 중 어디에 속하는지 알려줍니다.

릴리스 전 프로덕션 점검 목록

몇 가지 습관을 들이면 muse-image-1.0/text-to-image 호출이 노트북을 벗어난 뒤에도 예측 가능하게 유지됩니다:

  • 요청 구조를 고정하세요. API 참조 문서에 기록된 필드에 맞춰 JSON 요청 본문을 검증하세요. 매개변수를 추가할 경우 먼저 지원되는지 확인하세요.
  • 모든 곳에 타임아웃을 설정하세요. 생성 호출과 반환된 이미지 데이터의 모든 다운로드에는 명시적 타임아웃이 필요합니다.
  • 오류 범주를 구분하세요. 재시도 가능(429, 5xx) 실패와 종결성(400, 401, 403, 404, 422) 실패를 구분해야 경보가 시끄럽지 않고 재시도도 낭비되지 않습니다.
  • 핵심 정보를 기록하세요. 응답에 요청 ID가 있으면 그것, 상태 코드, 지연 시간, 프롬프트 길이를 기록하세요. 프롬프트에 민감한 텍스트가 포함될 수 있다면 프롬프트 자체는 기록하지 마세요.
  • 비용 요인에 주의하세요. 생성은 출력 기준으로 청구됩니다. 이미지 수, 크기, 재시도 빈도가 모두 비용에 영향을 줍니다. 종결성 오류를 재시도하지 말고, 결과 캐시가 가능할 때는 재생성을 피하세요.
  • 키를 서버 측에 보관하세요. 브라우저나 모바일 클라이언트에 API 키를 내장하여 엔드포인트를 직접 호출하는 일은 절대 하지 마세요.

이렇게 하면 통합은 어디서나 호출할 수 있는 작고 지루한 함수가 됩니다. 바로 그것이 원하는 것입니다. 전체 매개변수 면과 현재 응답 필드는 이 모델의 HiAPI API 참조 문서를 확인하세요.

관련 글

모든 아티클 보기 →

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

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

API 문서 보기