블로그

튜토리얼

HiAPI API로 grok-imagine/text-to-image 사용하는 방법: curl 및 Python 가이드

Nov 12, 2026
크림색과 흑연색의 레이어드 페이퍼 커버 아트로, 테라코타색 시트 한 장이 얕은 깊이로 계단식으로 배치되어 있습니다.
이 페이지에서

grok-imagine/text-to-image가 제공하는 것

grok-imagine/text-to-image는 HiAPI를 통해 제공되는 텍스트-이미지 엔드포인트입니다. JSON 형태로 HTTP를 통해 프롬프트와 몇 가지 생성 파라미터를 보내면 이미지를 돌려받습니다. 계약은 이게 전부입니다. SDK 설치도, 세션 초기화도, 첫 이미지를 보기 위한 백그라운드 작업 폴링도 필요 없습니다.

개발자 워크플로에서의 위치:

  • 프로토타입 검증. 터미널 명령 한 줄로 아이디어에서 렌더링된 이미지까지 갈 수 있어 프롬프트 아이디어를 빠르게 테스트할 수 있습니다.
  • 콘텐츠 파이프라인. 평범한 HTTP 호출이므로 백엔드 서비스, 큐 워커, 빌드 스크립트 어디서든 다른 API를 호출하듯 호출할 수 있습니다.
  • 제품 기능. 사용자 대상 이미지 생성은 보통 예측 가능한 요청/응답 처리, 구조화된 오류, 재시도를 의미합니다. 무상태 엔드포인트는 이 세 가지에 잘 맞습니다.

이 엔드포인트가 아닌 것: 프롬프트를 대신 저장하지 않고, 생성된 이미지 라이브러리를 관리하지 않으며, 여러분의 오케스트레이션을 대체하지 않습니다. 요청은 여러분의 책임이고, 출력도 여러분의 책임이며, 바이트가 어디로 갈지도 여러분이 결정합니다.

이 가이드는 요청을 일단 동작시키는 데 초점을 맞추고, 그다음 안정적으로 만드는 데 집중합니다. curl을 쓰든 Python을 쓰든 패턴은 완전히 같습니다. 둘 다 인증이 포함된 동일한 HTTP 요청이기 때문입니다. 최소 동작부터 시작해 왕복이 성공하는 것을 확인한 뒤 복잡도를 더하세요.

사전 요구 사항과 인증

첫 호출 전에 다음을 갖추었는지 확인하세요:

  1. HiAPI 계정과 API 키. 키는 기밀로 취급하세요. 환경 변수에서 불러오고, 커밋될 수 있는 스크립트에 절대 하드코딩하지 마세요.
  2. HTTP 요청을 보낼 도구. 첫 테스트에는 curl이면 충분합니다. Python의 경우 requests 또는 httpx를 사용하세요. 둘 다 뒤에서 다룹니다.
  3. HiAPI API 호스트에 대한 네트워크 접근. 회사 프록시 뒤에 있다면 curl과 Python 모두 읽을 수 있도록 셸에 HTTPS_PROXY를 설정하세요.

키는 bearer 토큰으로 Authorization 헤더를 통해 전달됩니다:

export HIAPI_API_KEY="your-key-here"

그러면 모든 요청에 다음이 포함됩니다:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

즉시 들여야 할 두 가지 습관:

  • 키를 URL에 넣지 마세요. 요청의 어느 부분에도 자격 증명을 쿼리 문자열에 넣지 마세요. 결국 로그와 셸 기록에 남습니다.
  • 환경마다 다른 키를 사용하세요. 개발 키와 프로덕션 키는 서로 다른 값이어야 하므로 하나를 회전해도 다른 하나에 영향을 주지 않습니다.

아직 키를 생성하지 않았다면 HiAPI 대시보드에서 생성하고 시크릿 관리자에 저장하거나 버전 관리에서 제외된 로컬 .env 파일에 넣으세요. echo $HIAPI_API_KEY가 값을 출력하면 첫 요청을 보낼 준비가 된 것입니다.

curl에서의 최소 동작 요청

최소한의 유용한 호출은 모델 식별자와 프롬프트만 보냅니다. 나머지는 모두 기본값을 가지므로 이미지가 돌아오는 것을 보기 전에 파라미터 조정에 나서지 마세요.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light"
  }'

각 부분의 역할:

  • -X POST와 JSON 요청 본문은 생성 엔드포인트의 표준 형식입니다.
  • model은 grok-imagine/text-to-image를 명시적으로 선택합니다. 스크립트에서는 기본값에 의존하지 말고 모델 이름을 고정하세요. 그래야 기본값 변화가 조용히 출력을 바꾸지 않습니다.
  • prompt는 유일한 콘텐츠 입력입니다. 첫 테스트에서는 명확한 한 문장으로 유지하세요.

성공 응답은 생성된 이미지를 포함한 JSON을 반환하며, 요청한 응답 형식에 따라 보통 URL 또는 base64 페이로드입니다. 파싱 코드를 작성하기 전에 JSON 포매터로 응답을 읽어보세요. 터미널에서 출력을 보는 경우 python -m json.tool로 파이프하면 구조를 더 읽기 쉽게 만들 수 있습니다.

동작하면 원시 응답을 파일에 저장하여 알려진 정상 기준선을 확보하세요:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json \
  -o response.json

요청 본문을 request.json에 두면 셸 따옴표와 씨름하지 않고 프롬프트를 편집할 수 있습니다. 프롬프트가 길어지거나 구두점을 포함할 때 특히 중요합니다.

Python에서의 동일한 요청

Python 버전은 동일한 HTTP 호출이지만 사용감이 더 좋습니다. 중첩 따옴표 대신 딕셔너리를 쓰고 이미지 바이트를 직접 처리할 수 있습니다.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "grok-imagine/text-to-image",
    "prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light",
}

response = requests.post(
    f"{base_url}/v1/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

특히 짚어둘 두 가지 세부 사항이 있습니다. 첫째, timeout=120입니다. 이미지 생성은 즉각적이지 않으므로 타임아웃이 없는 요청은 업스트림이 멈추면 워커를 무한히 매달리게 합니다. 둘째, 파싱 전에 raise_for_status()를 호출하세요. 그래야 오류 응답 본문이 성공한 이미지 응답으로 오인되지 않습니다.

이미지를 저장하려면 두 가지 응답 형태를 모두 처리하세요:

item = data["data"][0]

if item.get("b64_json"):
    import base64
    image_bytes = base64.b64decode(item["b64_json"])
else:
    image_bytes = requests.get(item["url"], timeout=60).content

with open("output.png", "wb") as f:
    f.write(image_bytes)

단일 의존성 집합을 선호한다면 httpx도 동일하게 사용할 수 있습니다. httpx.post(..., json=payload)를 쓰면 됩니다. 핵심은 요청 본문과 헤더가 curl 예제와 완전히 동일하다는 점입니다. 이 일관성 덕분에 두 예제가 서로 교환 가능하고 디버깅이 예측 가능해집니다.

종횡비에 맞춘 프롬프트 구성

와이드 출력은 특정 방식으로 실패합니다. 모델에는 채워야 할 수평 공간이 많으므로 요소를 반복하거나 아주 작은 주제를 텅 빈 화면에 띄워 놓습니다. 형용사를 더 쌓는 대신 프롬프트 구조로 해결하세요.

세 부분 골격을 사용하세요:

  1. 주제 — 이미지가 무엇에 관한 것인지, 먼저 그리고 구체적으로 말합니다. "항구로 들어오는 화물선"이 "배"보다 낫습니다.
  2. 스타일 — 렌더링 언어: 사진, 플랫 벡터, 수채화, 영화 스틸. 한두 단어면 충분합니다.
  3. 구도 — 화면을 어떻게 구성할지. 와이드 비율의 성패가 여기서 갈립니다.

구도의 경우 수평 구조를 명시적으로 이름 붙이세요:

  • 왼쪽에서 오른쪽으로 또는 파노라마식 읽기 순서를 지정하세요: "와이드 원경, 주제는 오른쪽 3분의 1에, 왼쪽은 열린 하늘."
  • 전경, 중경, 배경을 분리된 띠로 묘사하세요. 와이드 화면은 자연스럽게 층으로 읽히기 때문입니다.
  • 가장자리를 무엇으로 채울지 명시하세요: "가장 왼쪽에 항구 크레인, 가장 오른쪽에 열린 물." 가장자리는 와이드 이미지에서 가장 먼저 비는 곳입니다.
  • 인물 사진이나 정사각형 구도를 암시하는 프롬프트—얼굴 클로즈업, 중앙에 놓인 단일 물체—는 피하고, 늘어나거나 레터박스가 생길 것을 예상하세요.

파노라마 형식에 맞게 종횡비 파라미터를 설정할 때는 프롬프트도 함께 바꾸세요. 정사각형 화면용으로 쓴 프롬프트는 와이드 캔버스에서 정사각형 개념을 만들어냅니다. 지평선, 거리, 줄지은 물체, 방에 흩어진 군중처럼 수평 거리를 포함하는 장면으로 다시 쓰세요.

한 번에 변수 하나만 반복하세요. 종횡비를 고정하고 표현을 바꿔본 뒤, 표현을 고정하고 비율을 바꿔보세요. 둘 다 출력과 함께 기록하면 어떤 변경이 실제로 도움이 되었는지 판단할 수 있습니다.

오류와 응답 코드 처리

상태 코드를 먼저 읽고, 그다음 응답 본문을 읽으세요. 흔한 실패는 각각 다른 수정법을 가리키므로 이를 혼동하면 시간을 낭비합니다.

401 Unauthorized

키가 없거나, 형식이 잘못되었거나, 폐기되었습니다. 헤더가 정확히 Authorization: Bearer <key>인지, 환경 변수가 실제로 확장되었는지(값이 아니라 길이를 출력), 다른 환경의 키를 잘못 보내지 않았는지 확인하세요.

400 Bad Request

JSON이 유효한 HTTP이긴 하지만 해당 엔드포인트에는 유효하지 않습니다. 흔한 원인:

  • model의 철자가 틀렸거나 누락됨. 반드시 grok-imagine/text-to-image여야 합니다.
  • prompt가 비었거나 누락됨.
  • 일부 파라미터의 타입이 잘못됨—숫자여야 할 곳에 문자열이 있거나 그 반대.
  • 요청 본문이 애초에 유효한 JSON이 아님. 보통 curl의 셸 따옴표 문제에서 비롯됩니다. 요청 본문을 파일로 옮기고 -d @request.json을 사용하세요.

오류 메시지 본문을 읽으세요. 보통 문제가 된 필드를 지목합니다.

429 Too Many Requests

할당량보다 빠르게 요청을 보내고 있습니다. 해결책은 클라이언트 쪽에 있습니다: 백오프, 대기열, 재시도. 429를 받았다고 재시도 루프를 더 조이지 마세요. 상황이 더 나빠집니다.

5xx 서버 오류

일시적이거나 업스트림 상태입니다. 지연 후 재시도하고, 여러 시도 후에도 실패가 지속되면 무한 재시도 대신 요청 페이로드와 응답 본문을 캡처해 진단하세요.

타임아웃과 연결 오류

이들은 HTTP 상태 코드가 아니지만 실무에서 가장 흔한 실패입니다. requests가 연결 타임아웃을 던지면 요청이 이미 처리되었을 수도 있습니다. 재시도 루프를 작성하기 전에 사용 사례에서 타임아웃이 "재시도"를 뜻하는지 "포기"를 뜻하는지 먼저 정하세요.

프로덕션에서의 튜닝과 재시도

기준선 요청이 동작하면 조금씩 튜닝하세요. 먼저 프롬프트 표현을 바꾸고, 다음 종횡비를 바꾸고, 그다음 다른 파라미터를 바꾸며 출력을 나란히 비교하세요. 각 요청 페이로드를 출력과 함께 저장하면 결과를 항상 재현할 수 있습니다.

프로덕션 래퍼는 세 가지를 합니다. 재시도할 가치가 있는 실패만 재시도하고, 디버깅에 충분한 로그를 남기며, 포기할 때는 크게 실패합니다.

import time
import requests

def generate(payload, max_attempts=4):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(
                f"{base_url}/v1/images/generations",
                headers=headers,
                json=payload,
                timeout=120,
            )
        except requests.RequestException as exc:
            log.warning("request failed attempt=%d err=%s", attempt, exc)
            time.sleep(2 ** attempt)
            continue

        if r.status_code == 429 or r.status_code >= 500:
            log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
            time.sleep(2 ** attempt)
            continue

        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")

        return r.json()

    raise RuntimeError("exhausted retries")

이 패턴에 대한 설명:

  • 상한이 있는 지수 백오프(2 ** attempt)는 속도 제한을 받은 클라이언트가 엔드포인트를 반복해서 몰아치지 않게 합니다. 워커를 많이 돌린다면 지터를 추가하세요.
  • 429, 5xx, 네트워크 오류만 재시도하세요. 400이나 401은 매 시도마다 동일하게 실패합니다.
  • 시도 횟수와 상태를 기록하되 API 키는 기록하지 말고, 프롬프트에 사용자 데이터가 포함될 수 있다면 전체 프롬프트를 절대 기록하지 마세요.
  • 총 시간을 제한하세요. 상한 없는 재시도 루프는 느린 요청 하나를 멈춘 워커로 바꿉니다.

지연과 성공률을 가정하지 말고 직접 측정하세요. 이 두 숫자가 병렬성을 더 늘려야 하는지 백오프를 더 늘려야 하는지 알려줍니다. 이 가이드의 최소 요청으로 시작해 위의 헬퍼 함수로 감싸고, 그곳에서 반복하세요.

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

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

API 문서 보기