HiAPI API로 ideogram-v3-character 사용하는 방법: curl + Python 가이드

ideogram-v3-character란 무엇이며, 언제 사용해야 할까

ideogram-v3-character는 HiAPI에서 캐릭터 일관성에 초점을 맞춘 이미지 생성 모델입니다. 매 생성마다 독립적인 프롬프트로 처리하지 않고, 캐릭터의 참조 이미지를 제공할 수 있어 이후 렌더링에서도 동일한 얼굴, 의상, 전반적인 정체성 특징을 유지합니다.

누구인가와 무엇을 하는가가 똑같이 중요할 때 사용해야 합니다:

• 스토리보드와 만화: 동일한 캐릭터가 여러 컷에 등장합니다.
• 게임 에셋 변형: 주인공 캐릭터의 다양한 포즈, 표정, 의상을 생성합니다.
• 브랜드 마스코트: 다양한 장면과 배경에서 일관된 모습을 유지해야 합니다.
• 반복적인 아트 디렉션: 유사성을 잃지 않으면서 여러 차례 조정하며 캐릭터를 다듬습니다.

일회성 일러스트만 필요하고 이전 이미지와의 일치가 중요하지 않다면 범용 텍스트-투-이미지 모델이 더 간단합니다. 참조 이미지가 제공하는 추가 구조가 바로 ideogram-v3-character에 요청 필드를 추가할 가치가 있는 이유입니다.

이 모델은 다른 모델과 마찬가지로 통합 HiAPI 이미지 생성 엔드포인트를 통해 노출되므로 요청 구조가 익숙하게 느껴질 것입니다. JSON 페이로드를 보내고, 비동기 작업의 작업 참조를 받아, 결과가 준비될 때까지 폴링합니다. 이 튜토리얼은 이 흐름을 올바르게 수행하는 방법에 초점을 맞춥니다.

요청을 보내기 전: 설정 및 인증

첫 호출 전에 몇 가지만 준비하면 됩니다.

1. API 키

HiAPI 계정 대시보드에서 API 키를 생성하세요. 기밀로 취급하세요. 모든 요청을 인증하며 계정 청구에 반영됩니다.

2. 환경 변수 기반 자격 증명 처리

키를 소스 파일에 하드코딩하거나 git에 커밋하지 마세요. 대신 환경 변수를 사용하세요:

export HIAPI_API_KEY="your_api_key_here"

Python에서는 다음과 같이 읽을 수 있습니다:

import os
api_key = os.environ["HIAPI_API_KEY"]

로컬 개발에서 .env 파일을 사용한다면 다른 작업을 하기 전에 먼저 .gitignore에 추가하세요.

3. 참조 이미지 URL

캐릭터 일관성은 참조 이미지에 의존하므로 URL로 전달할 수 있는 이미지를 준비하세요. 해당 URL이 공개적으로 접근 가능하거나 API가 접근할 수 있는 방식인지 확인하세요. 인증 뒤에 있는 비공개 링크는 실패합니다. 정사각형 또는 세로형이면서 캐릭터 얼굴이 선명하게 보이는 이미지가 가장 좋습니다.

4. HTTP 요청을 보내는 방법

명령줄의 curl 또는 requests가 설치된 Python 환경 중 하나면 충분합니다. 아래 예시는 둘 중 하나를 갖추고 있다고 가정합니다.

이 네 가지를 준비했다면 첫 요청을 보낼 수 있습니다.

작동하는 curl 요청 줄별 분석

다음은 HiAPI에 ideogram-v3-character 작업을 제출하는 전체 요청입니다. 플레이스홀더를 자신의 값으로 바꾸세요.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-character",
    "prompt": "햇살이 비치는 작업실에 서서 렌치를 들고 있는 친근한 로봇 정비공, 4분의 3 각도",
    "reference_images": [
      "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1
  }'

각 부분의 역할

• POST /v1/images/generations — 통합 HiAPI 이미지 생성 엔드포인트입니다. 모든 모델이 동일한 경로를 사용합니다.
• Authorization: Bearer $HIAPI_API_KEY — 호출을 인증합니다. 셸이 앞서 설정한 환경 변수를 확장합니다.
• Content-Type: application/json — JSON 본문을 보내므로 이를 선언해야 합니다.
• model — ideogram-v3-character를 선택합니다. 이것이 없으면 요청이 어느 모델로 라우팅될지 알 수 없습니다.
• prompt — 장면 설명입니다. 포즈, 환경, 조명, 분위기를 설명하고, 캐릭터의 정체성은 참조 이미지에 맡기세요.
• reference_images — 이미지 URL 배열입니다. 단일 캐릭터의 경우 보통 항목 하나면 충분합니다.
• aspect_ratio — 출력 형태입니다. 의도한 용도에 맞추세요(정사각형, 세로형 등).
• num_images — 작업당 몇 개의 변형을 생성할지입니다.

성공적으로 제출하면 작업 식별자가 포함된 JSON 본문이 반환됩니다. 해당 값을 기록하세요. 폴링 단계에서 필요합니다. 응답에는 작업이 대기 중인지 처리 중인지 나타내는 상태 필드가 포함될 수도 있습니다. 상태가 이미 종료 상태라면 결과가 응답에 직접 포함될 수 있습니다. 그렇지 않으면 계속 폴링하세요.

Python에서 동일한 요청

다음은 Python에서의 완전히 동일한 호출입니다. 환경 변수에서 키를 읽고 요청을 보내며 작업 참조를 출력합니다.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "ideogram-v3-character",
    "prompt": "햇살이 비치는 작업실에 서서 렌치를 들고 있는 친근한 로봇 정비공, 4분의 3 각도",
    "reference_images": [
        "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=60)
response.raise_for_status()

job = response.json()
print(json.dumps(job, indent=2))

job_id = job.get("id") or job.get("job_id")
print("Job id:", job_id)

Python 버전에 대한 참고 사항

• timeout=60은 네트워크가 좋지 않을 때 스크립트가 무한정 멈추는 것을 방지합니다.
• raise_for_status()는 2xx가 아닌 응답을 예외로 변환하여 인증 및 검증 문제를 즉시 알아차리게 합니다.
• 작업 ID 추출 — HiAPI는 응답 본문에 작업 식별자를 반환합니다. 응답 구조에 따라 id 또는 job_id 아래에 있을 수 있습니다. 예시는 둘 다 확인하지만, 실제 응답을 먼저 확인한 후 명확성을 위해 올바른 필드명을 하드코딩해야 합니다.

페이로드는 의도적으로 curl 예시와 완전히 동일합니다. 둘 사이에서 JSON 본문을 복사해 오가는 것은 디버깅 시 좋은 정합성 검사입니다. 하나는 되고 다른 하나가 안 된다면 문제는 모델이 아니라 전송 계층에 있습니다.

캐릭터 일관성을 위한 참조 이미지 처리

참조 이미지가 바로 ideogram-v3-character를 일반 텍스트-투-이미지 모델과 구별 짓는 요소입니다. 참조 이미지를 잘 처리하면 작업의 절반 이상을 완료한 것입니다.

참조 이미지를 제공하는 방법

reference_images 필드는 URL 배열입니다. 각 URL은 API가 직접 가져올 수 있는 이미지를 가리켜야 합니다. 사용자 업로드 콘텐츠를 저장한다면 인증되지 않은 GET 요청을 허용하는 버킷이나 CDN에서 제공하거나, 작업이 실행되는 동안 유효한 서명 URL을 생성하세요.

실제로 일관성을 유지하는 참조 이미지 팁

• 참조 이미지마다 캐릭터 하나만 포함하세요. 단체 사진은 어떤 얼굴을 유지해야 할지 판단하기 어렵게 만듭니다.
• 얼굴이 선명하고 조명이 좋아야 합니다. 짙은 그림자, 극단적인 각도, 가림을 피하세요.
• 중립적이거나 특징적인 포즈. 정면 또는 4분의 3 각도가 정체성 특징을 가장 잘 유지합니다.
• 의상을 유지하고 싶다면 참조 이미지의 의상이 일관되어야 합니다 — 모델은 보이는 것을 재현합니다.
• 해상도는 중요하지만 과하지 않게. 크기가 적당하고 얼굴이 선명한 이미지가 거대하고 흐릿한 이미지보다 낫습니다.

여러 생성에서 캐릭터를 식별 가능하게 유지하기

같은 캐릭터로 두 번째 장면을 생성할 때는 이전에 생성한 출력이 아니라 동일한 참조 이미지를 재사용하세요. 생성된 이미지를 체인으로 사용하면 미세한 드리프트가 누적될 수 있습니다. 새 참조 이미지가 필요하다면(예: 다른 의상) 한 번 생성하고, 확인한 후, 해당 파일을 이후 작업의 새 참조 이미지로 재사용하세요.

일관성 검증

같은 캐릭터로 서로 다른 포즈의 변형을 두세 개 생성하고 나란히 비교하세요. 얼굴이나 의상이 드리프트한다면 보통 원인은 약하거나 모호한 참조 이미지입니다. 프롬프트를 바꾸기 전에 먼저 참조 이미지를 더 엄격하게 다듬으세요.

비동기 작업: 제출, 폴링 및 결과 가져오기

이미지 생성에는 시간이 걸리므로 HiAPI는 비동기 방식으로 처리합니다. 패턴은 항상 같습니다. 제출하고, 작업 ID를 캡처하고, 작업이 종료 상태에 도달할 때까지 폴링한 후 출력 URL을 읽습니다.

작업 생명주기

1. 제출 — 앞선 예시의 요청을 보냅니다.
2. 대기 중 — 작업이 접수되어 용량을 기다리고 있습니다.
3. 처리 중 — 모델이 렌더링하고 있습니다.
4. 완료 또는 실패 — 종료 상태이며 결과(또는 오류)를 사용할 수 있습니다.

Python에서 폴링

job_id를 캡처한 후 작업 엔드포인트를 폴링하세요:

import time
import requests

def wait_for_job(job_id, api_key, interval=2, max_attempts=60):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data
        if status in ("failed", "error", "canceled"):
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

결과 가져오기

작업이 완료되면 응답 본문에 출력이 포함됩니다. 보통 이미지 URL 배열 또는 단일 URL과 메타데이터입니다. 해당 URL에서 가능한 한 빨리 이미지를 다운로드하세요. 일부 URL은 시간 제한이 있습니다. 장기 저장이 필요하다면 작업 성공 직후 파일을 자신의 버킷에 복사하세요.

폴링 에티켓

• 백오프. 2초 간격은 짧은 작업에는 괜찮습니다. 많은 작업을 폴링한다면 간격을 늘리거나 지터를 사용하세요.
• 시도 횟수를 제한하세요. max_attempts 가드는 무한 루프를 방지하고 코드에 명확한 실패 경로를 제공합니다.
• 필요 이상으로 빠르게 폴링하지 마세요. 매 폴링은 하나의 요청입니다. 엔드포인트를 두드린다고 렌더링이 더 빨리 끝나지 않습니다.

흔한 오류와 진단 방법

문제가 생겼을 때 가장 빠른 경로는 보통 문제가 요청, 참조 이미지, 작업 자체 중 어디에 있는지 분리하는 것입니다.

인증 실패

401은 키가 누락되었거나 형식이 잘못되었거나 폐기되었음을 의미합니다. 요청을 실행하는 셸이나 프로세스에 환경 변수가 실제로 설정되어 있는지 확인하세요. 흔한 함정: 한 터미널에서 변수를 설정하고 다른 터미널에서 스크립트를 실행하는 경우입니다.

검증 오류

400은 거의 항상 페이로드를 가리킵니다. 다음을 확인하세요:

• model 필드가 정확히 ideogram-v3-character인지.
• reference_images가 문자열이 아닌 배열인지.
• 배열의 각 URL이 공개적으로 접근 가능한지.
• aspect_ratio가 지원되는 값을 사용하는지.

확실하지 않다면 최소 페이로드 — model, prompt, reference_images만 — 를 보낸 후 필드를 하나씩 다시 추가하세요.

완료되지 않는 작업

폴링이 시도 한도를 초과하면 무작정 재시도하지 마세요. 작업 상태 응답에 메시지가 있는지 확인하세요. 흔한 원인은 참조 URL에 접근할 수 없거나 큐가 과부하된 것입니다. 한 번 다시 제출하세요. 다시 멈춘다면 프롬프트와 참조 이미지를 단순화하세요.

참조 이미지가 조용히 무시됨

작업은 성공했지만 캐릭터가 일치하지 않습니다. 이는 보통 코드 문제가 아니라 참조 이미지 문제입니다. URL이 오류 페이지, PDF 또는 플레이스홀더 이미지를 반환할 수 있습니다. 브라우저에서 직접 해당 URL을 가져와 예상한 이미지가 올바른 콘텐츠 유형으로 반환되는지 확인하세요.

속도 제한

429는 요청을 너무 빠르게 보냈음을 의미합니다. 지수 백오프를 사용하세요. 대량 생성 중이라면 한꺼번에 모두 보내지 말고 제출을 분산하세요.

빠른 점검 목록

• 키가 올바른 환경에 설정되어 있나요?
• 참조 URL이 인증 없이 접근 가능한가요?
• 페이로드 필드 철자가 올바른가요?
• 폴링에 상한과 백오프가 설정되어 있나요?
• 출력이 URL 만료 전에 다운로드되었나요?

이 목록을 순서대로 확인하면 대부분의 실패를 빠르게 해결할 수 있습니다. 처음 엔드투엔드 실행이 성공하면 이를 알려진 정상 예시로 보관하고 새로운 요청을 이와 비교하세요. 많은 캐릭터와 장면으로 확장할수록 이 습관만으로도 시간을 절약할 수 있습니다.