튜토리얼

grok-imagine-quality 텍스트-이미지 API 사용법: curl, Python 및 바로 실행 가능한 요청

Jul 11, 2026

요약

무엇인가: hiapi에서 grok-imagine-quality/text-to-image API를 사용하는 실행 가능한 방안 — POST /v1/tasks로 작업을 생성하고, GET /v1/tasks/<taskId>를 폴링하거나(또는 콜백 사용), output[0].url에서 이미지를 다운로드합니다.
스키마는 엄격하고 간결합니다: prompt(필수), aspect_ratio(13가지 비율, 기본값 1:1), resolution(1k | 2k, 소문자, 기본값 1k), output_format(jpeg | png | webp, 기본값 jpeg). 다른 필드는 400으로 거부됩니다.
"Quality"는 등급이지 조정 항목이 아닙니다. quality나 rich_detail 파라미터는 존재하지 않습니다 — 더 풍부한 디테일, 질감, 조명은 이 모델 변형이 기본으로 제공하는 것입니다. 저렴한 대량 초안이 필요하다면 같은 엔드포인트에 표준 등급의 자매 모델 grok-imagine/text-to-image가 있습니다.
출력 URL에는 expireAt 마감 시각이 있습니다 — 제때 다운로드하거나 영구 저장하세요.

무엇을 만들고 무엇을 준비해야 하나

목표: grok-imagine-quality/text-to-image에 텍스트 프롬프트를 보내고 주요 비주얼로 쓸 수 있는 완성된 이미지 파일을 받아오기 — 먼저 curl로, 그다음 작업 큐에 넣을 수 있는 작은 Python 스크립트로 작성합니다.

필요한 것은 단 하나: hiapi API 키. hiapi 콘솔에서 발급받아 내보내세요:

export HIAPI_API_KEY="sk-..."

모든 요청은 표준 bearer 헤더로 인증합니다: Authorization: Bearer sk-<key>.

최소 실행 요청(curl)

hiapi의 이미지 생성은 비동기 전용입니다. 긴 HTTP 호출을 기다릴 필요 없이, 작업을 생성하고 완료 후 결과를 가져옵니다.

1단계 — 작업 생성:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "슬레이트 조리대 위에 놓인 무광 블랙 에스프레소 머신의 제품 히어로 샷, 드라마틱한 방향성 조명, 얕은 심도, 고급 상업적 질감",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

모델이 백그라운드에서 작업하는 동안 즉시 taskId를 받습니다:

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

2단계 — 종료 상태가 될 때까지 폴링:

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

작업은 queued → handling → archiving을 거쳐 최종적으로 success 또는 fail에 도달합니다. success만 출력을 포함합니다:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

3단계 — expireAt 전에 다운로드:

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

Python에서의 동일한 흐름

완전한 스크립트 — 생성, 폴링, 저장. 복사하고 HIAPI_API_KEY를 설정한 뒤 실행하세요.

import os
import time

import requests

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

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "슬레이트 조리대 위에 놓인 무광 블랙 에스프레소 머신의 제품 히어로 샷, "
            "드라마틱한 방향성 조명, 얕은 심도, 고급 상업적 질감"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # 소문자! "2K"는 400으로 거부됩니다
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # 여기서 4xx = 요청 자체가 거부됨
task_id = resp.json()["data"]["taskId"]
print("작업 생성됨:", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("hero.png 저장됨")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"작업 실패: {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving —— 계속 폴링

2k 등급 생성은 보통 1~2분 내에 완료됩니다; 5초 폴링 간격이면 충분합니다.

실제로 존재하는 파라미터

입력 스키마는 엄격합니다 — 알 수 없는 필드는 조용히 무시되지 않고 400 INVALID_REQUEST: additional properties not allowed로 실패합니다. 이는 좋은 소식입니다: 오타가 프로덕션까지 흘러가지 않습니다. 전체 인터페이스 범위:

필드	필수	값	기본값
`input.prompt`	예	자유 텍스트	—
`input.aspect_ratio`	아니오	`2:1`, `20:9`, `19.5:9`, `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`, `9:19.5`, `9:20`, `1:2`	`1:1`
`input.resolution`	아니오	`1k`, `2k`(소문자만)	`1k`
`input.output_format`	아니오	`jpeg`, `png`, `webp`	`jpeg`

이를 기반으로 구축하기 전에 알아둘 세 가지:

이름 속 "quality"는 등급이지 파라미터가 아닙니다. 이 모델이 더 풍부한 디테일, 질감, 조명을 갖는다고 설명되는 것을 볼 수 있는데 — 그것은 모델 변형 자체입니다. 토글할 수 있는 rich_detail, quality, style 필드는 없습니다.
1k와 2k는 다른 등급으로 과금됩니다. 일반적인 패턴: 1k에서 프롬프트를 반복 개선한 뒤, 승리한 프롬프트로 2k에서 다시 실행해 최종 자료를 생성합니다. 현재 이미지당 가격은 hiapi 가격 페이지를 참고하세요.
n도, seed도, negative_prompt도 없습니다. 작업 하나에 이미지 하나를 생성합니다. 변형이 필요하면 여러 작업을 병렬로 제출하세요 — 서로 독립적이며 동시에 대기열에 들어갑니다.

프로덕션 고려사항: 콜백, 멱등성, 오류

프로덕션 환경에서는 폴링보다 콜백을 우선하세요. 요청 본문 최상위(input 내부가 아님)에 callback을 전달하면, 작업이 종료 상태에 도달할 때 hiapi가 귀하의 서비스를 호출합니다:

{
  "model": "grok-imagine-quality/text-to-image",
  "input": { "prompt": "..." },
  "callback": {
    "url": "https://your-service.example.com/hiapi/callback",
    "when": "final"
  }
}

when: "final"을 사용하면 success와 fail 모두 알림을 받으므로, 귀하 측에서 taskId로 중복 제거하세요. 콜백이 유실될 경우를 대비해 저빈도 폴링을 폴백으로 유지하세요 — 작업 상세 엔드포인트는 항상 사실의 원천입니다.

Idempotency-Key로 재시도를 안전하게 만드세요. 작업 생성은 Idempotency-Key 헤더(최대 255바이트)를 받습니다. 같은 키로 재시도하면 중복 작업이 절대 생성되지 않습니다 — 재전송은 원래 taskId를 반환합니다:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

세 가지 실패 형태를 구분해 처리하세요:

인증 실패 — HTTP 401 및 {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. 키와 해당 키가 이 모델을 사용할 권한이 있는지 확인하세요; 맹목적으로 재시도하지 마세요.
잘못된 입력 — HTTP 400 및 "error_code": "INVALID_REQUEST", 메시지가 구체적 필드를 지목합니다(예: resolution: value must be one of '1k', '2k'). 페이로드를 수정하세요; 같은 요청 본문으로 재시도하면 동일하게 실패합니다.
작업 수준 실패 — 생성 호출은 성공했지만 작업이 status: "fail"과 data.error 객체로 종료됩니다. 다시 제출하기 전에 error.code를 확인하세요.

expireAt을 주의하세요. 출력 URL은 임시입니다. 작업 성공 즉시 파일을 다운로드하거나, 생성 시 storage: "persistent"를 전달해 출력을 장기 보관하세요.

자주 묻는 질문

grok-imagine-quality와 grok-imagine/text-to-image의 차이는 무엇인가요? 같은 엔드포인트, 같은 요청 구조, 다른 등급. quality 등급은 주요 비주얼과 상업적 자료를 위한 것으로 더 풍부한 디테일과 조명을 제공하며 1k/2k 해상도 등급으로 가격이 책정됩니다; 표준판 grok-imagine/text-to-image는 대량 처리와 아이디어 구상을 위한 더 빠르고 저렴한 옵션입니다.

왜 "resolution": "2K"는 400을 반환하나요? 열거형은 대소문자를 구분하며 소문자입니다: 1k 또는 2k. 대문자 값은 INVALID_REQUEST로 거부됩니다.

1920x1080 같은 정확한 픽셀 크기를 설정할 수 있나요? 아니요. aspect_ratio(2:1 초광폭부터 9:20 초세로까지 13가지 옵션)로 형태를 제어하고, 1k/2k 등급으로 선명도를 제어합니다. 이 모델에는 자유 형식의 size 필드가 없습니다.

한 요청에서 여러 이미지를 생성할 수 있나요? 아니요 — n 파라미터가 없습니다. 여러 작업을 병렬로 제출하세요; 각 작업은 자체 taskId를 반환하고 동시에 처리됩니다.

grok-imagine-quality는 이미지-투-이미지를 지원하나요? 지원합니다. 별도 모델 id인 grok-imagine-quality/image-to-image를 사용하세요. 해당 스키마는 이미지-투-이미지 방안을 참고하세요 — 텍스트-투-이미지와 다릅니다.

결과 URL의 유효 기간은 얼마나 되나요? 각 output[] 항목에는 expireAt Unix 타임스탬프가 있습니다. 해당 마감 시각 전에 다운로드하거나, 작업 생성 시 storage: "persistent"를 사용하거나(또는 나중에 출력을 승격하여) 보존하세요.

대기열에 있지만 완료되지 않은 작업은 어떻게 보이나요? GET /v1/tasks/<taskId>가 반환하는 status는 queued, handling 또는 archiving이며, 아직 output이 없습니다. success만 다운로드 가능한 출력을 포함합니다; fail은 data.error를 포함합니다.

핵심 요점

모델 id는 grok-imagine-quality/text-to-image이며 POST /v1/tasks로 호출 — 비동기 전용; GET /v1/tasks/<taskId>를 폴링하거나 callback.url 및 when:"final"을 전달하세요
엄격한 입력 스키마: prompt(필수), aspect_ratio(13가지 비율, 기본값 1:1), resolution(소문자 1k|2k, 기본값 1k), output_format(jpeg|png|webp) — 알 수 없는 필드는 400 반환
"Quality"는 모델 등급이지 파라미터가 아닙니다 — rich_detail/quality 조정 항목은 없습니다; 저렴한 대량 초안에는 표준판 grok-imagine/text-to-image를 사용하세요
1k와 2k는 다른 등급으로 과금됩니다: 1k에서 프롬프트를 반복 개선한 뒤, 승리한 프롬프트로 2k에서 실행해 최종 자료를 생성하세요
출력 URL은 만료됩니다(expireAt) — 즉시 다운로드하거나, 작업 생성 시 storage:"persistent"를 사용하세요; Idempotency-Key 헤더로 재시도를 안전하게 만드세요