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

Imagen 4 Ultra는 Google Imagen 4 시리즈에서 디테일 수준이 가장 높은 버전이며, hiapi에서는 다른 모든 이미지 모델과 마찬가지로 동일한 통합 비동기 태스크 API를 통해 텍스트-이미지 생성을 실행합니다. 이 가이드는 실제로 끝까지 실행되는 요청을 제시합니다. 실제 curl 호출, Python 폴링 루프, 서버가 실제로 받아들이는 파라미터, 그리고 실제 요청으로 검증된 오류 상황을 담았습니다. 아래의 모든 내용은 게시 전에 프로덕션 엔드포인트에서 실행 검증되었으며, 예시 taskId와 출력 URL은 그 실행에서 나온 것입니다.

구축할 내용

한 번의 호출로 텍스트 프롬프트를 완성된 이미지로 바꿉니다. POST /v1/tasks로 태스크를 제출하고, 완료될 때까지 폴링한 다음, output[0].url에서 이미지 URL을 읽습니다. hiapi API key가 필요합니다. 대시보드에서 발급받아 내보내세요:

export HIAPI_API_KEY="your-hiapi-key"

최소 실행 예제(curl)

이 모델은 prompt와 선택적 aspect_ratio를 받습니다. 태스크를 생성합니다:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "input": {
      "prompt": "Macro product photo of a matte ceramic coffee mug on a pale oak table, soft window light from the left, shallow depth of field, a few coffee beans in the foreground, no text, no logos",
      "aspect_ratio": "4:3"
    }
  }'

생성 호출은 즉시 태스크 id를 반환하고, 생성은 백그라운드에서 계속됩니다:

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

반환된 id로 태스크를 폴링합니다:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

status가 success이면 이미지는 output[0].url에 있습니다:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61",
    "model": "imagen-4.0-ultra",
    "status": "success",
    "storage": "temp",
    "created": 1792506471,
    "completed": 1792506479,
    "output": [
      {
        "artifactId": "279760",
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5CVC8R62M0Z7CCM8WB38B61-0.webp",
        "expireAt": 1793111279
      }
    ]
  },
  "message": "success"
}

해당 실행은 약 8초 만에 완료되었고 WebP(PNG/JPEG 아님)를 반환했습니다. URL은 임시 저장소에 있으며("storage": "temp"), expireAt은 7일 후로 설정되어 있습니다. 제때 다운로드하고 핫링크하지 마세요.

프로덕션 환경: 폴링 루프가 있는 Python

생성 응답에는 이미지가 포함되지 않고 taskId만 있습니다. 실제 통합은 먼저 제출한 다음 폴링하거나(또는 콜백을 사용) 합니다. 이 스크립트는 전체 왕복을 수행하고 URL이 임시이므로 결과를 즉시 다운로드합니다:

import os, time, requests

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

def generate(prompt, aspect_ratio="1:1", negative_prompt=None, seed=None):
    body = {"model": "imagen-4.0-ultra", "input": {"prompt": prompt, "aspect_ratio": aspect_ratio}}
    if negative_prompt:
        body["input"]["negative_prompt"] = negative_prompt
    if seed is not None:
        body["input"]["seed"] = str(seed)  # seed is a STRING, not a number

    r = requests.post(API, headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    created = r.json()
    if created.get("code") != 200:
        raise RuntimeError(f"create rejected: {created}")
    task_id = created["data"]["taskId"]

    # Poll. Statuses other than success/fail (e.g. queued, running, archiving) mean "keep waiting".
    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # tolerate a transient read; re-poll the same id
        status = d.get("status")
        if status == "success":
            return d["output"][0]["url"]
        if status in ("fail", "failed", "error"):
            raise RuntimeError(f"task failed: {d}")
    raise TimeoutError(f"task {task_id} did not finish in time")

url = generate(
    "A high-detail aerial landscape of terraced rice fields at golden hour, long shadows",
    aspect_ratio="16:9",
)
img = requests.get(url, timeout=60).content
open("out.webp", "wb").write(img)
print(f"saved {len(img)} bytes from {url}")

프로덕션에서 중요한 주의사항:

• 폴링 vs 콜백. 위에서는 폴링을 보여줍니다. 폴링을 피하려면 최상위 callback 객체({"url": "...", "when": "final"})를 붙이면 태스크가 종료 상태에 도달할 때 hiapi가 POST 요청을 보냅니다. 콜백 계약은 통합 비동기 API 문서를 참조하세요.
• 저장된 id를 다시 폴링하고, 새로 생성하지 마세요. 태스크 읽기는 멱등입니다. 연결이 끊기면 GET /v1/tasks/<id>를 재시도하고, 절대 다시 POST하지 마세요(이미지 한 장이 추가로 과금됩니다).
• 성공하면 즉시 다운로드하세요. output[0].url은 임시입니다(이번 실행에서 TTL은 7일). 바이트를 받아 자체 저장소로 옮기세요.

이 모델이 실제로 받는 파라미터

imagen-4.0-ultra는 텍스트-이미지만 지원합니다. 참조 이미지는 지원하지 않습니다(모델 페이지에서 확인됨, 이번 실행에서는 텍스트-이미지만 테스트). 입력 스키마는 닫혀 있습니다. 알 수 없는 필드는 거부되므로 추가 파라미터를 몰래 넣을 수 없습니다.

필드	타입	필수	설명
prompt	string	예	1–5,000자. 빈 문자열은 실패합니다(minLength: got 0, want 1).
aspect_ratio	enum	아니요	1:1, 16:9, 9:16, 3:4, 4:3, auto 중 하나. 기본값은 1:1.
negative_prompt	string	아니요	최대 5,000자. 제외할 내용을 설명합니다.
seed	string	아니요	최대 500자. 문자열이며 숫자를 전달하면 거부됩니다.

하나의 요청은 정확히 한 장의 이미지를 생성합니다.

검증된 오류 상황

이들은 실제 엔드포인트에서 발생한 것이므로 오류 처리에서 신뢰할 수 있습니다. 거부된 요청은 HTTP 400과 플랫 봉투를 반환하며 taskId가 없습니다:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: aspect_ratio: value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'"}

코드에서 고려할 만한 동작:

• 검증기는 모든 필드 오류를 한 번에 보고합니다, ; 로 연결합니다. seed에 숫자를 전달하고 aspect_ratio가 잘못되면 하나의 메시지에서 둘 다 받게 됩니다: invalid input: seed: got number, want string; aspect_ratio: value must be one of .... 응답마다 오류가 하나라고 가정하지 마세요.
• 알 수 없는 필드는 전체 요청을 실패시킵니다, 오류는 <root>: additional properties '<name>' not allowed. 스키마는 닫혀 있습니다.
• 빈 프롬프트는 prompt: minLength: got 0, want 1 오류로 실패합니다.
• 성공한 create는 code: 200이고 data.taskId가 있습니다. 거부되면 data: null입니다. 태스크 id를 읽기 전에 이에 따라 분기하세요.

어떤 Imagen 4 티어를 호출해야 할까?

imagen-4.0-ultra는 세 티어 중 최상위입니다. 관성보다 태스크 기준으로 선택하세요(가로세로 비율, 네거티브 프롬프트, 시드는 지불 비용에 영향을 주지 않습니다. 가격 참조):

• Imagen 4 Fast — 가장 저렴하며 초안 훑어보기와 방향 대량 탐색에 적합합니다.
• Imagen 4 — 일상적인 중간 티어로 제품, 라이프스타일, 콘텐츠 이미지에 적합합니다.
• Imagen 4 Ultra(이 모델) — 세 가지 중 가장 비싸며 완성품 수준의 디테일에 초점을 둡니다: 매크로 질감, 재질 렌더링, 텍스트 레이아웃으로 최종 이미지가 검증을 견뎌야 하는 장면에 적합합니다. 출력을 바로 납품할 때 Ultra를 선택하고, 반복 작업에는 Fast나 기본 티어를 사용하세요.

관련 링크

• Imagen 4 Ultra 모델 페이지 — 실시간 스키마, 예제, 가격.
• 통합 비동기 API 문서 — 태스크 생성/목록/조회와 콜백 계약.
• 빠른 시작 — 몇 분 안에 인증하고 첫 태스크를 실행하세요.
• 가격 — Imagen 4 각 티어의 이미지당 비용.

자주 묻는 질문

요청 하나에 이미지가 몇 장 반환되나요? 한 장입니다. 검증된 실행에서 output 배열은 항목 하나만 포함했습니다.

출력 형식은 무엇인가요? WebP입니다. 반환된 파일은 temp.hiapi.ai의 .webp입니다.

출력 URL은 얼마나 유효한가요? 약 7일입니다. expireAt은 완료 후 7일로 설정됩니다. 임시 리소스로 취급하고 즉시 다운로드하세요.

참조 이미지를 보낼 수 있나요? 아니요. imagen-4.0-ultra는 텍스트-이미지만 지원하며, 모델 페이지에서 참조 이미지를 지원하지 않는 것으로 명시합니다.

왜 요청에서 "additional properties not allowed" 오류가 나나요? 입력 스키마가 닫혀 있습니다. prompt, aspect_ratio, negative_prompt, seed만 보내세요. 다른 키가 있으면 전체 요청이 실패합니다.

네거티브 프롬프트, 시드, 가로세로 비율이 가격을 바꾸나요? 아니요. 이미지당 과금되며 이 파라미터들은 비용에 영향을 주지 않습니다.