튜토리얼
HiAPI API로 ideogram-v4.5를 사용하는 방법: curl, Python 및 동작하는 요청
HiAPI의 ideogram-v4.5가 제공하는 것
이미지 속 텍스트가 정말로 중요할 때 ideogram-v4.5가 바로 선택해야 할 모델입니다. 포스터 레이아웃, 로고 그래픽, 패키지 목업, 소셜 카드—한 군데 철자가 틀린 제목이나 흐릿한 캡션 하나로 소재가 망가지는 모든 상황이 바로 이 모델의 가치가 드러나는 지점입니다. 읽을 수 있어야 할 것이 아무것도 없는 추상 텍스처나 사진 풍경을 생성한다면, 범용 이미지 모델이 보통 더 저렴하고 빠릅니다.
이 글은 통합 가이드이며 모델 평가가 아닙니다. 다 읽고 나면 동작하는 요청 하나, 동일한 작업을 수행하는 Python 클라이언트, 그리고 사람들이 흔히 실수하는 부분—종횡비 파라미터, 비동기 작업 폴링, 출력 가져오기—을 처리하는 재사용 가능한 헬퍼 함수를 갖게 됩니다.
일찍부터 체득해야 할 점 하나: HiAPI의 이미지 생성은 비동기 작업 API입니다. 요청을 제출하고 식별자를 받은 뒤 완료될 때까지 폴링합니다. 응답 본문에 이미지가 이미 포함되어 있다고 가정하는 코드는 동작하지 않습니다. 아래의 모든 섹션이 이 패턴을 향해 나아갑니다.
요청을 보내기 전에
첫 호출 전에 네 가지를 준비해야 합니다.
1. API 키
HiAPI 계정 콘솔에서 생성하고 소스 코드 관리에서 멀리 두세요. 스크립트에 붙여넣지 말고 환경 변수로 내보내세요:
export HIAPI_API_KEY="your_key_here"
2. 기본 URL
모든 요청은 HiAPI API 기본 URL에 생성 엔드포인트의 구체적인 경로를 덧붙여 전송됩니다. 플랫폼 문서에 현재 경로가 나열되어 있으니, 문서가 다르게 말한다면 블로그 글(이 글 포함)에서 본 경로를 하드코딩하지 마세요.
3. 모델 식별자
요청 본문에 전달하는 모델 문자열이 ideogram-v4.5를 식별합니다. 플랫폼 모델 목록에 표시된 정확한 대소문자를 사용하세요—모델 식별자는 문자 그대로 일치하므로, 조금만 달라져도 유용한 제안이 아니라 검증 오류가 반환됩니다.
4. 파라미터 참조
ideogram-v4.5의 모델 페이지는 요청 본문이 어떤 필드를 허용하는지에 대한 권위 있는 출처입니다: 프롬프트 길이 제한, 지원되는 종횡비, 출력 형식, 그리고 시드나 스타일 제어가 있다면 그것까지. 코드를 작성하기 전에 한 번 읽으세요. 거기에 나열되지 않은 파라미터는 조용히 무시되거나 거부될 수 있으며, 값을 추측하는 것이 디버깅 시간을 낭비하는 가장 흔한 방식입니다.
이 네 가지가 있으면 첫 요청을 보낼 수 있습니다.
동작하는 curl 요청
아래는 최소 제출 예시입니다. 계정에 표시된 값이 다르면 플랫폼 문서의 엔드포인트 경로와 모델 식별자로 교체하세요.
curl -X POST "$HIAPI_BASE_URL/<generation-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.5",
"input": {
"prompt": "A vintage travel poster for the Amalfi Coast, bold serif headline reading \"AMALFI\", warm sunset palette, grainy print texture"
}
}'
각 부분의 역할:
Authorization— bearer token 인증. 헤더가 없거나 형식이 잘못된 것이 401의 가장 흔한 원인입니다.Content-Type— 반드시application/json이어야 합니다. 일부 HTTP 클라이언트는 POST 시 이를 자동으로 설정하지 않아 서버에서 혼란스러운 파싱 오류가 발생합니다.model— 리터럴 모델 식별자. 문서에 표시된 대로 요청 본문의 최상위에 둡니다.input.prompt— 생성 지시문. 위에 표시된 것처럼 이미지 안에 렌더링되길 원하는 텍스트를 따옴표로 감싸면 모델이 이를 설명이 아닌 리터럴 문구로 처리합니다.input.*— 다른 모든 생성 파라미터(종횡비, 형식, 시드 등)는prompt와 나란히 이 중첩 객체에 속합니다.
성공적으로 제출하면 작업 식별자와 상태 필드가 포함된 JSON 객체가 반환됩니다. 이 응답에는 이미지가 없습니다—이것이 예상 동작입니다. 식별자를 저장하세요; 폴링 단계에서 사용합니다.
Python으로 동일한 호출하기
Python 버전은 일대일 번역입니다. requests를 사용하며 동일한 요청 본문을 공유하므로 나란히 비교할 수 있습니다.
import os
import json
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
GEN_PATH = "/<generation-path>" # confirm in platform docs
payload = {
"model": "ideogram-v4.5",
"input": {
"prompt": (
"A vintage travel poster for the Amalfi Coast, bold serif "
'headline reading "AMALFI", warm sunset palette, grainy print texture'
)
},
}
response = requests.post(
BASE_URL + GEN_PATH,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=30,
)
response.raise_for_status()
job = response.json()
print(job)
두 가지 의도적인 선택:
json=대신json.dumps— 전송 형식을 curl 예시와 눈에 보이게 일치시킵니다. 둘 다 동작하지만, 명시적으로 작성하면 디버깅 시 실제로 보낸 내용을 더 쉽게 확인할 수 있습니다.timeout=30— 제출에만 사용됩니다. 제출은 빠르고 생성은 빠르지 않습니다. 제출 호출이 폴링용으로 설정된 짧은 타임아웃을 상속받게 하지 마세요. 그렇지 않으면 정상 작동하는 작업을 실패로 보고하게 됩니다.
출력된 job 딕셔너리에는 작업 식별자와 현재 상태가 포함됩니다. 식별자를 어딘가에 저장하세요—폴링 루프가 이에 의존합니다.
종횡비와 출력 형식 제어하기
종횡비와 출력 형식은 별도의 엔드포인트가 아니라 요청 본문 파라미터입니다. 프롬프트와 같은 input 객체에 위치합니다:
{
"model": "ideogram-v4.5",
"input": {
"prompt": "...",
"aspect_ratio": "<ratio from docs>",
"output_format": "<format from docs>"
}
}
여기서 중요한 규율은 값을 추측하지 않는 것입니다. 각 생성 모델은 고정된 비율과 형식 열거형을 노출하며, 모델마다 허용하는 표기법도 다릅니다—16:9 vs 16x9, png vs PNG 등. 모델이 지원하지 않는 값을 전달하면 보통 검증 오류가 발생하거나, 더 나쁘게는 조용히 기본 출력으로 대체되어 프롬프트의 버그처럼 보입니다.
그래서 작업 흐름은 다음과 같습니다:
- 플랫폼에서 ideogram-v4.5 모델 페이지를 열고 지원되는 종횡비 목록과 출력 형식 목록을 문자 그대로 복사합니다.
- 이 값들을 코드 내 작은 화이트리스트에 넣어 잘못된 입력이 API에 도달하기 전에 호출 지점에서 실패하게 합니다.
- 다운스트림 레이아웃과 일치하는 비율을 기본값으로 사용합니다. 이미지가 1200×630 소셜 카드 위치에 들어간다면 정사각형을 생성한 뒤 내용을 잘라내는 대신 그 비율에 가까운 값을 선택하세요.
텍스트가 밀집된 이미지에는 한 가지 추가 경고를 할 만합니다: 극단적인 비율(초광폭 배너, 초고층 포스터)은 텍스트 렌더링에 사용할 수 있는 공간을 압축합니다. 정말로 읽을 수 있어야 하는 제목의 경우, 파노라마식 극단 비율보다 중간 정도의 가로 또는 세로 비율이 더 안전합니다.
비동기 작업 처리 및 결과 다운로드
한 번의 생성 수명 주기는 세 단계로 나뉩니다: 제출 → 폴링 → 가져오기.
제출
앞선 섹션에서 이미 이 단계를 마스터했습니다. 응답은 작업 식별자와 queued 또는 processing 같은 상태를 제공합니다.
폴링
해당 식별자로 작업 상태 엔드포인트를 폴링하여 상태가 완료를 보고할 때까지 기다립니다. 두 가지 규칙이 이 과정을 품위 있게 유지합니다:
- 폴링 사이에 잠자기. 약 1초에서 시작해 점진적으로 백오프하세요. 상태 엔드포인트를 두들겨도 작업이 더 빨리 완료되지 않으며, 속도 제한에 걸릴 위험이 있습니다.
- 대기 시간을 제한. 최대 시도 횟수나 마감 시간을 설정하고, 초과 시 무한 루프 대신 명확한 오류를 발생시키세요.
import time
def wait_for_job(job_id, headers, base_url, status_path,
max_attempts=60, initial_delay=1.0, factor=1.5):
delay = initial_delay
for _ in range(max_attempts):
r = requests.get(
f"{base_url}{status_path}/{job_id}",
headers=headers,
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in ("succeeded", "completed", "success"):
return data
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {data}")
time.sleep(delay)
delay *= factor
raise TimeoutError(f"job {job_id} did not finish in time")
계정의 정확한 상태 문자열과 상태 경로는 플랫폼 문서를 참고하세요—문서의 값으로 일치시키고, 인식할 수 없는 상태는 성공이 아니라 여전히 실행 중인 것으로 취급하세요.
가져오기
작업이 완료를 보고하면 응답에 출력 위치(보통 URL)가 포함됩니다. 일반 GET으로 다운로드하여 바이트를 디스크에 기록하세요. 출력 URL에는 시간 제한이 있을 수 있으므로 나중에 쓰려고 URL을 저장하지 말고 가능한 한 빨리 다운로드하세요. 이 루프를 작성하는 데 필요한 모든 것은 제출 응답의 구조에서 나옵니다—배울 별도의 '이미지 가져오기' API는 없습니다.
재사용 가능한 헬퍼 함수로 캡슐화하기
폴링을 각자 다시 구현하는 세 개의 인라인 스크립트는 유지보수 문제입니다. 한 번 포장하세요.
import os, json, time, requests
class IdeogramClient:
def __init__(self, base_url, api_key, gen_path, status_path,
poll_attempts=60, poll_factor=1.5):
self.base_url = base_url.rstrip("/")
self.gen_path = gen_path
self.status_path = status_path
self.poll_attempts = poll_attempts
self.poll_factor = poll_factor
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
def generate(self, prompt, **params):
body = {"model": "ideogram-v4.5", "input": {"prompt": prompt, **params}}
r = requests.post(self.base_url + self.gen_path,
headers=self.headers,
data=json.dumps(body), timeout=30)
r.raise_for_status()
job = r.json()
done = self._wait(job["id"])
url = done["output"]["url"] # confirm shape in docs
return self._download(url)
def _wait(self, job_id):
delay = 1.0
for _ in range(self.poll_attempts):
r = requests.get(f"{self.base_url}{self.status_path}/{job_id}",
headers=self.headers, timeout=30)
r.raise_for_status()
data = r.json()
if data.get("status") in ("succeeded", "completed", "success"):
return data
if data.get("status") in ("failed", "error", "cancelled"):
raise RuntimeError(data)
time.sleep(delay)
delay *= self.poll_factor
raise TimeoutError(job_id)
def _download(self, url):
r = requests.get(url, timeout=60)
r.raise_for_status()
return r.content
사용할 때는 한 번의 호출이면 됩니다: img_bytes = IdeogramClient(...).generate("...", aspect_ratio="<from docs>"). done["output"]["url"] 접근 방식과 상태 문자열을 문서의 응답 구조에 맞게 조정하세요—이 두 곳이 계정별로 미세 조정이 가장 필요할 수 있는 지점입니다.
흔한 오류와 디버깅 팁
첫 주의 실패 대부분은 다섯 가지 범주에 속합니다.
401 / 403 — 인증. 키 누락, 복사-붙여넣기 중 공백 포함, 또는 Bearer 접두사 누락. 실제로 보낸 키의 앞뒤 네 글자씩을 출력해 보세요; 환경 파일에서 온 후행 개행이 전형적인 범인입니다.
400 — JSON 형식 오류 또는 알 수 없는 필드. 요청 본문을 문자열 연결로 조립했다면 프롬프트 내 이스케이프되지 않은 따옴표가 JSON을 깨뜨립니다. 본문을 딕셔너리로 구성하고 json.dumps로 직렬화하세요. JSON이 파싱된다면 다음 용의자는 모델이 허용하지 않는 파라미터 이름입니다—키를 모델 페이지와 문자 단위로 대조하세요.
404 / 모델을 찾을 수 없음. 보통 모델 식별자의 철자나 대소문자 오류, 또는 엔드포인트 경로가 오래된 경우입니다. 기억이나 오래된 튜토리얼이 아니라 플랫폼 문서에서 둘 다 복사하세요.
429 — 속도 제한. 거의 항상 폴링이 너무 공격적이기 때문입니다. 초기 폴링 지연과 백오프 계수를 늘리세요. 제출 측에서는 429 및 5xx 응답에 지터를 포함한 재시도를 추가하되, 4xx 검증 오류는 재시도하지 마세요—매번 동일하게 실패합니다.
작업은 성공했는데 이미지가 열리지 않음. JSON 오류 페이지가 아니라 바이트를 다운로드했는지 확인하세요; 다운로드 GET에 raise_for_status()를 호출하면 이런 문제 대부분을 잡을 수 있습니다. 또한 다운로드 URL을 세션 간 캐시하지 말고 단기 유효로 취급하는지 확인하세요.
확신이 서지 않을 때는 호출 체인의 모든 호출—제출, 각 폴링, 다운로드—에 대해 전체 응답 본문과 상태 코드를 기록하세요. API는 보통 어디가 잘못됐는지 명확히 알려줍니다; 버그는 보통 우리가 보지 않았기 때문입니다.
동작하는 제출, 폴링 루프, 합리적인 오류 처리가 있으면 ideogram-v4.5를 다른 어떤 HiAPI 모델 호출과 마찬가지로 실제 파이프라인에 연결할 수 있습니다.
관련 글
모든 아티클 보기 →-
튜토리얼
HiAPI API로 hailuo-2.3-fast/image-to-video 호출하는 방법: curl과 Python 실전
빠르고 저렴한 이미지-투-비디오 등급의 첫 실행 요청 — 모델 ID부터 MP4 다운로드까지
-
튜토리얼
HiAPI API로 hailuo-2.3/text-to-video를 호출하는 방법: curl, Python 및 실행 가능한 요청 예시
-
튜토리얼
HiAPI에서 Kandinsky 6.0 Pro 텍스트-투-비디오 사용하기: curl 및 Python 튜토리얼
요청 우선 실전 데모: 프롬프트에서 비디오 클립까지의 호출 구성, 요청 제출, 완료 상태 폴링 및 결과 다운로드