Imagen 4 API는 어떻게 사용하나요? 5분 만에 첫 이미지 생성하기

TL;DR

• Imagen 4(imagen-4.0)는 텍스트-투-이미지 모델로, 한 장에 $0.06: 프롬프트 한 문장 쓰고 화면 비율 고르면 이미지가 나옵니다. 인물 사진, 자연 클로즈업, 제품 정물에 적합합니다. 모델 페이지 열기에서 바로 온라인으로 시도할 수 있고, 신규 사용자 가입 시 200 크레딧을 드립니다.
• 같은 시리즈에 두 가지 등급이 더 있습니다: imagen-4.0-fast는 한 장에 $0.03으로 대량 시안 작업용, imagen-4.0-ultra는 한 장에 $0.09로 완성본 디테일용입니다.
• 호출은 HiAPI /v1/tasks 인터페이스로: 작업을 제출해 taskId를 받고, 결과를 조회한 뒤 성공하면 output[0].url에서 이미지를 다운로드합니다.

무엇을 할 수 있나

• 텍스트로 바로 이미지 생성: 참조 이미지를 받지 않으며, 화면 전체를 프롬프트로 설명하고 aspect_ratio는 필수(1:1, 16:9, 9:16, 3:4, 4:3, auto 여섯 가지)입니다.
• 세 가지 포지션, 하나의 시리즈: Fast는 시안, 표준 등급은 일상 생산, Ultra는 디테일 향상용으로, 세 모델 ID를 같은 프로젝트에서 단계별로 사용합니다.
• 매번 고정 1장: 장 수, 픽셀 크기, 출력 형식 파라미터는 없으며, 다시 실행하면 seed가 바뀝니다.

아래는 표준 등급의 실제 결과물입니다:

Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography

(중국어 의미: 햇살이 가득한 북유럽풍 거실, 린넨 소파, 오크 선반과 몬스테라 한 그루; 잡지 느낌의 실내 사진. 화면 비율 16:9 선택.)

imagen-4.0, 16:9, 1280×720, $0.06.

이 프롬프트로 생성 →

세 모델 선택 방법

	imagen-4.0-fast	imagen-4.0(표준)	imagen-4.0-ultra
장당	$0.03	$0.06	$0.09
포지션	대량 시안, 방향 선정	일상 생산	완성본 디테일, 질감과 텍스트 배치
$10로 약	333장	166장	111장
적합	기획 회의, 스케치 라운드	일반 이미지 납품	최종 확정, 디테일에 민감한 화면

예산 참고: 전부 표준 등급으로 월 1,000장 생산 시 약 $60.00; 시안 작업을 Fast로 옮길수록 청구서가 낮아지고, 확정 작업은 Ultra에 남겨두세요.

세 모델의 호출 방식은 같고 model 필드만 바꾸면 됩니다; 파라미터 구조도 동일하며 seed 타입만 차이가 있습니다(파라미터 표 참조). Fast와 Ultra에는 각각 영어판 연동 튜토리얼이 있습니다: Imagen 4 Fast API guide, Imagen 4 Ultra API guide. 시나리오별 프롬프트 선택은 프롬프트 대전을, 세 등급의 전체 가격표와 월 예산은 가격 페이지를, Nano Banana 2.1과의 두 세트 동일 프롬프트 비교는 비교 페이지를 참조하세요.

두 가지 시작 경로

브라우저 3단계: 모델 페이지 열기 → 프롬프트 붙여넣고 화면 비율 선택 → 생성 클릭, 표준 등급 한 장에 $0.06. 처음에는 브라우저에서 한 장 먼저 실행해 화면 스타일이 예상과 맞는지 확인한 뒤 코드를 작성하는 것을 권장합니다.

API 3단계: POST /v1/tasks 제출 → taskId 획득 → GET /v1/tasks/<taskId>로 success 확인 후 다운로드.

curl: 첫 이미지

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "imagen-4.0",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

등급을 바꾸려면 model만 변경: imagen-4.0-fast 또는 imagen-4.0-ultra. 응답의 taskId가 조회 증빙입니다.

Python: 제출, 폴링, 다운로드

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "imagen-4.0",
    "input": {
        "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
        "aspect_ratio": "16:9",
    },
}

# 제출: Idempotency-Key 포함, 네트워크 재시도 시 작업이 중복 생성되지 않음
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# 폴링: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 임시 주소, 가능한 빨리 다운로드하여 저장
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # 확장자는 실제 반환된 형식에 맞게 지정
        f.write(img.content)
    print("saved")

파라미터 표

필드	필수	값	설명
prompt	예	1–5000자	화면 내용 설명
aspect_ratio	예	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	출력 화면 비율, 필수
negative_prompt	아니오	≤5000자	원하지 않는 내용
seed	아니오	표준 및 Ultra: 문자열(≤500자); Fast: 정수	같은 파라미터와 같은 seed로 화면 재현

세 모델은 동일한 파라미터 표를 공유합니다. 요청 본문에 표 외 필드가 나타나면 바로 400입니다.

만나게 될 오류

상태 코드	의미	처리 방법
400 INVALID_REQUEST	요청 본문 부적합(prompt 또는 aspect_ratio 누락, 열거형 값 오류, 표 외 필드 전달)	파라미터 표에 맞춰 요청 본문 수정
402 INSUFFICIENT_QUOTA	잔액 부족(요금 미청구)	충전 후 재시도
429 RATE_LIMITED	속도 제한 발생	제출 빈도 낮추기
409 / 422 IDEMPOTENCY_KEY_*	동일 멱등 키 중복 제출(처리 중 / 파라미터 불일치)	새 Idempotency-Key로 변경
415 UNSUPPORTED_MEDIA_TYPE	요청 형식 오류	Content-Type: application/json 확인

작업 종료 상태가 실패인 경우 오류 코드에 CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT 등이 있습니다; 실패 시 요금이 청구되지 않으며, 사전 차감된 크레딧은 전액 환불됩니다.

출시 전 주의사항

• 콜백: 요청 본문 최상위에 "callback": {"url": "https://..."}를 전달하면 작업이 종료 상태에 도달할 때 서비스에 알려주므로 폴링을 생략할 수 있습니다.
• 즉시 이전 저장: output[0].url은 임시 주소이므로 받자마자 다운로드하여 자체 스토리지에 저장하세요.
• 화면 비율 명시: aspect_ratio는 필수 항목이므로 기본값에 의존하지 마세요; 세로형 소셜 미디어 콘텐츠는 9:16을 선택하세요.
• seed 타입은 모델별: Fast는 정수, 표준과 Ultra는 문자열을 전달하세요.

자주 묻는 질문

세 모델의 호출 방식이 같은가요?

같습니다. model 필드만 바꾸면 되고 다른 코드는 수정할 필요가 없습니다.

픽셀 크기나 출력 형식을 지정할 수 있나요?

아니요. 픽셀 크기와 형식 파라미터는 없으며, 출력 화면 비율은 aspect_ratio로 결정되고 매번 1장입니다.

실패하면 요금이 청구되나요?

아니요. 사전 차감된 크레딧은 실패 종료 상태 후 전액 환불됩니다.

화면 속 텍스트는 신뢰할 수 있나요?

확대해서 확인해야 합니다. 포스터류 이미지는 간혹 글자가 하나 더 많거나 획이 하나 빠질 수 있으니, 게시 전에 텍스트 부분을 확대해 한 번 점검하세요.

세 등급의 이미지를 한 프로젝트에 섞을 수 있나요?

가능합니다. 프롬프트와 화면 비율 로직은 공통입니다.

다음 단계: 위의 거실 프롬프트를 복사해 모델 페이지에서 한 장 시도해 보세요, 그런 다음 시나리오별로 프롬프트 대전의 템플릿을 골라 대량 생성하세요.