블로그

튜토리얼

HiAPI API로 gpt-image-2.6-flare/text-to-image 호출하는 방법: curl, Python 및 실행 가능한 요청

Nov 10, 2026
겹쳐진 반투명 유리 시트가 옅은 색면을 차가운 파란색 띠로 변화시키는 추상 커버 아트, 매트하고 건축적인 느낌, 텍스트 없음.
이 페이지에서

이 튜토리얼에서 만드는 것

대부분의 텍스트-이미지 튜토리얼은 성공 응답 스크린샷 한 장에서 끝납니다. 그것만으로는 아무것도 실제 서비스에 올릴 수 없습니다. 이 튜토리얼은 처음부터 HiAPI 통합 API와 gpt-image-2.6-flare/text-to-image 모델을 통해 재사용 가능하고 실행 가능한 통합을 구축하는 과정을 안내합니다.

끝나면 세 가지를 갖추게 됩니다:

  • 정상 작동이 확인된 요청 하나를, 먼저 curl 명령 형태로, 그다음 동등한 Python 스크립트로 제시합니다.
  • HiAPI가 텍스트-이미지 호출을 어떻게 구성하는지에 대한 명확한 멘탈 모델—엔드포인트 경로, 인증 헤더, 프롬프트 페이로드, 응답 본문—을 갖게 되어, 예제를 외우지 않고도 자신의 프롬프트에 맞게 변형할 수 있습니다.
  • 단일 호출을 배치 처리로 확장하는 패턴과, 어떤 실패는 재시도하고 어떤 실패는 수정해야 하는지 판단하는 방법을 익히게 됩니다.

코드는 간결하게, 의존성은 최소로 유지합니다. Python 예제는 표준 라이브러리만 사용하므로 Python이 설치된 어디서든 실행할 수 있으며, 요청 구조에 익숙해진 뒤 requests나 비동기 클라이언트로 변형하면 됩니다. 바로 실행 가능한 호출로 넘어가고 싶다면 curl 섹션으로 건너뛰고, 이후 설명을 읽으러 돌아오세요.

사전 준비 사항과 자격 증명

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

  1. HiAPI 계정. 대시보드에 로그인하여 자격 증명을 생성하고 관리하세요.
  2. API 키. 대시보드의 API 키 영역에서 생성하세요. 비밀번호처럼 다루세요: 계정으로 청구되는 모든 요청을 승인하는 키입니다.
  3. HTTP 요청을 보낼 수단. curl이 설치된 셸, 또는 표준 라이브러리가 포함된 Python 3(urllib과 json은 Python에 기본 포함)입니다.

환경 변수로 키 처리하기

키를 커밋될 소스 파일에 직접 붙여넣지 마세요. 대신 셸에서 내보내세요:

export HIAPI_API_KEY="your-api-key-here"

Windows PowerShell에서는 $env:HIAPI_API_KEY = "your-api-key-here"를 사용하세요. CI에서는 시크릿으로 주입하세요. 장기 실행 서비스에서는 시작 시 시크릿 관리자에서 로드하세요.

기본 URL 위치 파악하기

HiAPI는 단일 통합 API 표면을 제공하므로 기본 URL은 모델 간에 안정적으로 유지됩니다. 코드 곳곳에 흩어 놓지 말고 하나의 설정 값—환경 변수가 적합합니다—에 보관하세요. 그러면 스테이징과 프로덕션 간 전환이나 테스트를 mock 서버로 지정하는 것이 한 줄 변경으로 끝납니다.

호출할 모델 식별자는 gpt-image-2.6-flare/text-to-image입니다. 슬래시가 포함되어 있으니 주의하세요. 식별자를 온전히 유지하고, 아래 예제와 정확히 동일하게 요청 빌더가 기대하는 경로 위치에 두세요.

키를 내보내고 기본 URL을 기록했으니, 이제 요청 자체를 살펴볼 수 있습니다.

텍스트-이미지 요청의 구조

모든 HiAPI 텍스트-이미지 호출은 동일한 네 가지 구성 요소를 가집니다. 이를 이해하면 모델이나 프롬프트 전환은 기계적인 작업이 됩니다.

1. 엔드포인트 경로

요청은 모델 식별자를 경로의 일부로 사용합니다: 기본 URL 뒤에 이어지는 gpt-image-2.6-flare/text-to-image. 이것이 호출을 통합 인터페이스 뒤의 올바른 모델로 라우팅하는 주소입니다.

2. 인증 헤더

인증은 Authorization 헤더의 bearer 토큰입니다:

Authorization: Bearer $HIAPI_API_KEY

모든 요청에 이 헤더가 반드시 포함되어야 합니다. 누락이나 형식 오류는 첫 호출 실패의 가장 흔한 원인입니다.

3. 요청 본문

텍스트-이미지 호출은 JSON 본문을 가진 POST입니다. 핵심은 프롬프트—원하는 이미지에 대한 자연어 설명—입니다. 요청 본문에는 생성 설정도 담깁니다. HiAPI는 모델 간에 요청 구조를 정규화하므로, 요청 빌더를 재사용하고 출력을 비교하고 싶을 때 모델 식별자만 바꾸면 됩니다.

4. 응답 본문

성공 응답은 생성된 이미지(또는 그 참조)와 생성에 관한 메타데이터를 반환합니다. 클라이언트는 이미지를 파싱하기 전에 HTTP 상태를 확인해야 합니다. 응답을 눈으로 볼 대상이 아니라 데이터로 취급하세요—자동화에서는 이미지 바이트나 URL이 필요하고, 파일을 생성한 호출로 다시 연결할 수 있도록 요청 식별자를 함께 저장해야 합니다.

이것이 전체 모델입니다. 이후의 모든 내용은 이 네 부분의 구체적 적용일 뿐입니다.

curl로 실행 가능한 요청 보내기

다음은 완전한 호출입니다. 프롬프트를 자신의 텍스트로 바꾸고 실행하세요:

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
  }' \
  --output response.json

줄별 설명:

  • -X POST—생성은 상태를 변경하는 호출이므로 POST를 사용합니다.
  • URL—환경 변수에서 가져온 기본 URL 뒤에 모델 식별자와 /text-to-image가 이어집니다. 따옴표로 감싸면 셸이 특수 문자를 잘못 해석하지 않습니다.
  • Authorization: Bearer ...—자격 증명. $HIAPI_API_KEY 형태는 실제 키가 셸 기록에 남지 않게 합니다.
  • Content-Type: application/json—서버에 요청 본문을 JSON으로 파싱하라고 알립니다. 이를 생략하면 혼란스러운 4xx 오류가 발생하는 흔한 원인입니다.
  • -d '{...}'—JSON 페이로드. prompt 필드가 가장 자주 바꾸는 필드이며, 출력을 다듬을 때 여기에 생성 설정을 추가합니다.
  • --output response.json—응답 본문을 파일에 씁니다. 이렇게 하면 바이너리 이미지 페이로드가 터미널을 범람하지 않습니다. 파일을 열어보거나, 응답이 JSON 인코딩이면 jq로 파이프 처리하세요.

빠른 정상 작동 확인

명령이 신속히 반환되고 response.json이 비어 있지 않다면 작동하는 통합을 갖춘 것입니다. 대신 4xx가 나온다면 응답 본문을 확인하세요—HiAPI는 설명적인 오류를 반환하며, 아래 오류 처리 섹션에서 흔한 원인들을 다룹니다.

이것이 작동하면 명령을 프로젝트 옆의 셸 스크립트에 저장하세요. 자격 증명 변경을 테스트하거나 고장이 내 쪽인지 확인하는 가장 빠른 방법입니다.

Python으로 동일한 요청 보내기

curl 호출은 그대로 Python으로 옮길 수 있습니다. 이 스크립트는 표준 라이브러리만 사용하고, 환경 변수에서 키를 읽으며, 이미지 응답을 디스크에 씁니다:

import json
import os
import urllib.error
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"

def generate_image(prompt: str, settings: dict | None = None) -> bytes:
    payload = {"prompt": prompt}
    if settings:
        payload.update(settings)

    request = urllib.request.Request(
        f"{BASE_URL}/{MODEL}",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            return response.read()
    except urllib.error.HTTPError as exc:
        detail = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc

if __name__ == "__main__":
    body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
    with open("output.bin", "wb") as f:
        f.write(body)
    print(f"wrote {len(body)} bytes")

의도적인 선택 몇 가지:

  • 타임아웃을 넉넉하게 설정. 이미지 생성은 텍스트 완성보다 느립니다. 120초 상한은 영원히 멈추는 것을 방지하면서도 느리지만 성공하는 호출을 허용합니다.
  • 함수가 경로가 아닌 바이트를 반환. 이로써 재사용 가능해집니다—바이트를 객체 스토리지에 업로드하거나 웹 핸들러에서 반환할 수 있습니다.
  • 오류를 응답 본문과 함께 래핑. 실패하면 메시지가 상태 코드만이 아니라 서버가 무엇을 말했는지 알려줍니다.
  • 페이로드 빌더가 선택적 설정을 받음. 생성 파라미터를 추가할 때 함수에 하드코딩하지 말고 settings 딕셔너리를 확장하세요.

두 환경 변수를 내보낸 뒤 python generate.py로 실행하세요. requests를 더 선호한다면 요청 생성을 requests.post(url, json=payload, headers=headers)로 교체하세요. 구조는 완전히 동일합니다.

배치 처리와 동시성 패턴

프롬프트 하나는 데모이고, 많은 프롬프트는 실제 작업입니다. 이 전환은 처리량과 디버깅 가능성이라는 두 가지 문제를 낳습니다.

파일에서 프롬프트 반복하기

프롬프트를 줄바꿈으로 구분된 파일이나 JSON 배열에 넣으세요. 각 프롬프트에 ID(slug, 인덱스, 해시)를 부여하고 그 ID로 출력 파일의 이름을 지정하세요. 수백 장의 이미지 배치가 끝나면 추측 없이 각 파일을 원래 프롬프트로 매핑할 수 있습니다.

prompts = [
    ("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
    ("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
    body = generate_image(text)
    with open(f"out/{prompt_id}.bin", "wb") as f:
        f.write(body)

동시성을 명시적으로 제어하기

생성 호출은 I/O 집약적이므로 동시성이 처리량에 도움이 됩니다—하지만 무제한 동시성은 속도 제한을 유발하고 오류 수렁에 빠뜨립니다. 먼저 직렬로 실행하고 단일 호출 소요 시간을 측정한 뒤, 유한한 작업 풀로 동시성을 높이세요. 적은 수의 고정 작업 스레드(처음에는 4~8개)를 사용하는 간단한 스레드 풀로 보통 충분합니다.

더 큰 작업에는 비동기 클라이언트나 작업자 큐가 있는 큐를 사용하세요. 핵심 원칙은 동일합니다: 유한한 병렬성, 프롬프트 ID당 출력 파일 하나, 요청마다 ID, 상태, 소요 시간을 기록하는 로그 한 줄.

매니페스트 유지하기

배치 실행 중에 각 프롬프트 ID와 결과를 기록하는 작은 JSON 매니페스트를 작성하세요. 프로세스가 중간에 죽으면 매니페스트가 전체 배치를 다시 청구하지 않고 어디서부터 재개할지 알려줍니다. 이 관행은 어떤 영리한 최적화보다도 더 많은 시간을 절약합니다.

오류와 재시도 처리

실패는 두 범주로 나뉩니다: 수정하는 것과 재시도하는 것. 이를 혼동하면 시간을 낭비하고, 재시도 폭풍 속에서는 비용도 낭비합니다.

이것들을 수정하세요

  • 401 / 403—인증. 키 누락, 만료 또는 접근 권한 부족. HIAPI_API_KEY가 실제로 명령을 실행하는 셸에서 내보내졌는지 확인하세요—한 터미널에서 내보내고 다른 터미널에서 스크립트를 실행하는 것이 흔한 함정입니다.
  • 400—잘못된 페이로드 형식. 유효하지 않은 JSON, prompt 누락 또는 예상치 못한 필드 타입. 오류 본문이 보통 문제 필드를 지적합니다. curl 호출에서는 JSON 인용에 주의하세요.
  • 404—잘못된 경로. 모델 식별자 철자가 문서와 정확히 일치하는지, 기본 URL에 중복되거나 누락된 경로 세그먼트가 없는지 확인하세요.

이것들은 백오프와 함께 재시도하세요

  • 429—속도 제한. 속도를 늦추세요. 응답에 retry-after 힌트가 있으면 존중하고, 지터를 더한 지수 백오프를 사용하세요. 장기적으로는 동시성을 제한하세요.
  • 5xx—서버 오류. 보통 일시적입니다. 제한된 횟수(3회가 합리적인 기본값)로 지연을 늘려가며 재시도한 뒤 크게 실패하세요.

최소 재시도 래퍼

import random, time

def with_retries(fn, attempts=3):
    for i in range(attempts):
        try:
            return fn()
        except RuntimeError as exc:
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.uniform(0, 0.5))

이것으로 generate_image를 감싸세요. 핵심은 내 쪽에서 작업을 멱등적으로 만드는 것입니다. 출력 파일이 프롬프트 ID를 키로 하므로 재시도는 중복이 아니라 덮어쓰기가 됩니다. 실패할 때마다 프롬프트 ID와 서버 메시지를 기록하세요—실제로 에스컬레이션해야 할 때 그 로그가 바로 지원 팀이 문제를 재현하는 데 필요한 것입니다.

다음 단계

이제 작동하는 요청, 보관할 가치가 있는 Python 함수, 그리고 대규모로 실행하는 패턴을 갖추었습니다. 프로덕션을 위해 강화하려면 요청 ID가 포함된 구조화 로깅을 추가하고, 배치 작업이 크래시 후 복구되도록 매니페스트를 영구 저장소에 보관하며, 전송 전에 프롬프트를 검증하여 잘못된 입력이 빠르고 저렴하게 실패하도록 하세요.

가장 유용한 다음 단계는 HiAPI API의 다른 모델에서 이 동일한 클라이언트를 재사용하는 것입니다. 엔드포인트 경로, 인증 헤더, 페이로드 구조가 공유되므로 스크립트를 새 모델에 맞추는 일은 보통 모델 식별자를 바꾸고 가끔 설정 하나둘을 바꾸는 정도입니다—작은 코드 변경이 의미 있는 출력 차이를 만듭니다.

프롬프트 하나로 시작해 파일 생성이 되는지 확인하고, 나머지는 배치 실행기에 맡기세요.

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

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

API 문서 보기