imagen-4.0-fast API: 실제로 동작하는 텍스트-이미지 생성 요청

Imagen 4 Fast는 Google Imagen 4 시리즈의 속도 지향 모델이며, hiapi에서는 다른 모든 이미지 모델과 동일한 통합 비동기 태스크 API를 통해 텍스트-이미지 생성을 수행합니다. 이 가이드는 실제로 동작하는 요청을 제공합니다. 즉, 실제 curl 호출, Python 폴링 루프, 정확한 폐쇄형 입력 스키마, 그리고 실제 운영 환경에서 검증된 오류 사례를 담고 있습니다. 아래의 모든 내용은 게시 전에 프로덕션 엔드포인트를 대상으로 실행되었으며, 예시의 taskId와 출력 URL은 바로 그 실행에서 나온 것입니다.

구현하게 될 내용

한 번의 호출로 텍스트 프롬프트를 완성된 이미지로 변환합니다. POST /v1/tasks에 태스크를 제출하고, 완료될 때까지 폴링한 다음 이미지 URL을 읽습니다. hiapi API key가 필요합니다(콘솔에서 생성하고 계정에 종량제 크레딧을 보유하세요. 가격 참조). SDK는 필요 없으며, 여기의 모든 예시는 순수 HTTP입니다.

최소 동작 요청(curl)

태스크를 생성합니다. 모델 id는 imagen-4.0-fast이며, 이 모델에서는 aspect_ratio가 필수입니다(아래에서 자세히 설명).

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

생성 호출은 이미지가 아니라 태스크 핸들만 반환합니다.

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A" }, "message": "success" }

결과 폴링(Python)

taskId를 받은 후 GET /v1/tasks/<id>를 폴링하여 상태가 종료 상태에 도달할 때까지 기다립니다. 이것은 제가 실제로 실행한 루프입니다.

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen-4.0-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

제가 실행한 경우 상태는 약 12초 내에 handling → archiving → success 순으로 진행되었으며, 종료 상태 응답은 다음과 같았습니다.

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen-4.0-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

하나의 태스크는 하나의 WebP 이미지를 반환합니다. archiving 상태는 정상입니다. 잠시 머문 후 success로 전환됩니다.

입력 스키마(서버가 실제로 허용하는 내용)

input 객체는 폐쇄형 스키마입니다. 다음 필드만 허용합니다.

필드	타입	필수	설명
prompt	string	예	비어 있으면 안 됨; 빈 문자열은 minLength: got 0, want 1을 반환합니다.
aspect_ratio	enum	예	1:1, 16:9, 9:16, 3:4, 4:3, auto 중 하나. 기본값 없음.
seed	integer	아니오	재현 가능한 실행에 사용. JSON 숫자여야 하며 문자열은 안 됩니다.
negative_prompt	string	아니오	이미지에서 피하고 싶은 내용을 설명합니다.

이 모델에는 resolution 또는 size 필드가 없습니다. 출력 크기는 aspect_ratio를 따릅니다. 이 표 이외의 모든 필드는 거부됩니다.

검증된 오류 사례(주의할 함정)

이것들은 추측이 아니라, 라이브 엔드포인트에서 실제로 캡처한 400 응답입니다.

1. aspect_ratio 누락. 기본 Imagen 4 또는 Ultra 모델에서 코드 스니펫을 복사할 때의 가장 큰 함정입니다. 그쪽에서는 aspect_ratio가 1:1로 기본 설정되기 때문입니다. Fast에는 기본값이 없습니다.

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed를 문자열로 전송. 숫자로 전달하세요.

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. 알 수 없는 필드(여기서는 resolution) — 폐쇄형 스키마는 모든 추가 내용을 거부합니다.

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'resolution' not allowed" }

형태에 주목하세요. 검증 실패는 HTTP 400이며 error_code: "INVALID_REQUEST"를 포함하고, taskId가 없으며, message는 각 필드 오류를 ;로 구분된 하나의 문자열로 집계합니다. 따라서 첫 문장만이 아니라 전체 내용을 읽어야 합니다.

Fast와 Imagen 4 시리즈의 다른 모델 비교

hiapi는 완전히 동일한 태스크 API에서 세 가지 Imagen 4 모델을 호스팅합니다. model id만 다르므로 위의 요청 본문은 모든 모델에서 그대로 사용할 수 있습니다.

• imagen-4.0-fast — 속도 지향 모델(모델 페이지)이며 시리즈에서 비용이 가장 낮은 옵션입니다. 프롬프트 반복, 콘셉트 탐색, 대량 방향 탐색, 즉 많은 후보를 생성하고 소수만 유지하는 작업에 적합합니다.
• imagen-4.0 — 표준 Imagen 4 모델.
• imagen-4.0-ultra — 최고 디테일 모델로, 납품 수준의 최종 결과물에 사용합니다.

실용적인 워크플로: Fast에서 프로토타입을 만든 다음 model 문자열을 imagen-4.0-ultra로 바꾸어 최종 렌더링을 수행하세요. 다른 코드는 전혀 변경할 필요가 없습니다. 현재 이미지당 가격은 가격 페이지에서 비교하세요.

프로덕션 환경 유의사항

• 폴링 vs. webhook. 위의 루프는 폴링입니다. 프로덕션에서는 hiapi 태스크 API가 webhook도 지원합니다. model/input과 같은 레벨에 url과 when: "final"을 포함하는 최상위 callback 객체를 추가하면 hiapi가 태스크가 종료 상태에 도달할 때 태스크 세부 정보를 POST합니다. 이를 의존하기 전에 비동기 API 문서에서 전달 및 재시도 규약을 먼저 읽어보세요.
• 네트워크가 불안정할 때 다시 제출하지 마세요. 태스크를 생성할 때마다 새로운 taskId가 반환되며, 프롬프트에는 중복 제거가 없습니다. 폴링 요청이 일시적으로 실패하면 이미 저장한 taskId로 다시 폴링하세요. taskId를 한 번도 받지 못한 경우에만 다시 POST하면 됩니다.
• 출력 URL은 만료됩니다. output[].url은 temp.hiapi.ai에 있으며 expireAt은 약 7일 후입니다(위 예시는 2026-10-28에 만료). 바이트를 즉시 자체 스토리지로 다운로드하세요. 핫링크하지 마세요.

관련 콘텐츠

• Imagen 4 Fast 모델 페이지
• Imagen 4 Ultra — 최고 디테일 모델, 요청 구조 동일
• Imagen 4(기본 버전)
• 통합 비동기 태스크 API 문서
• 가격

자주 묻는 질문

Imagen 4 Fast는 다른 엔드포인트나 SDK가 필요한가요? 아닙니다. POST /v1/tasks에 "model": "imagen-4.0-fast"를 붙이면 됩니다. hiapi의 모든 이미지 및 비디오 모델이 사용하는 동일한 엔드포인트입니다. 모델 id를 변경하여 모델을 전환하세요.

왜 제 요청이 400과 함께 “missing required field aspect_ratio”를 반환하나요? Fast에는 기본 가로세로 비율이 없습니다(기본 버전 및 Ultra 모델과 다름). 항상 열거형 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto 중에서 aspect_ratio를 전송하세요.

해상도나 이미지 크기를 설정할 수 있나요? 아닙니다. 이 모델에는 resolution 또는 size 필드가 없으며, 출력 크기는 aspect_ratio를 따릅니다. resolution을 전송하면 additional properties 'resolution' not allowed가 반환됩니다.

seed는 문자열인가요, 숫자인가요? 숫자입니다. "seed": 7은 동작하며, "seed": "7"은 seed: got string, want integer를 반환합니다.

출력 URL의 유효 기간은 얼마나 되나요? 약 7일(expireAt)입니다. 즉시 다운로드하여 저장하세요.