튜토리얼

Grok Image 2.0 텍스트→이미지 API 사용법은? 5분 만에 첫 이미지 생성하기

curl 및 Python 실행 가능 예제, 네 가지 파라미터, 콜백과 출시 전 유의사항, 장당 $0.052.

Oct 12, 2026

Grok Image 2.0 텍스트→이미지 API 사용법은? 세 단계: POST /v1/tasks로 작업을 생성하고, taskId를 받은 뒤 폴링(또는 콜백 설정)하고, data.output[0].url에서 생성 이미지를 다운로드합니다. 장당 $0.052, 1K와 2K 동일 가격.

Grok Image 2.0은 HiAPI에 출시되었습니다. 모델 페이지 열기에서 바로 생성할 수 있으며, 신규 사용자 가입 시 200 크레딧을 지급해 먼저 1장을 생성해 결과를 확인할 수 있습니다.

TL;DR

무엇인가: grok-imagine-image-2.0/text-to-image, xAI가 만든 텍스트→이미지 모델이며 HiAPI의 통합 비동기 작업 인터페이스를 사용합니다.
얼마인가: 장당 $0.052, 1K / 2K, low / medium, 모든 화면 비율이 동일 가격입니다. 성공적으로 생성된 이미지 기준으로 과금되며 실패 시 자동 환불됩니다. $10로 약 192장 생성 가능.
가장 빠른 호출 방법: prompt 하나로 이미지를 생성할 수 있으며, 선택적으로 aspect_ratio, resolution, quality 세 가지 파라미터를 사용할 수 있습니다.

Grok Image 2.0 텍스트→이미지에는 어떤 파라미터가 있나요?

input에는 네 개의 필드만 있습니다:

필드	필수	값	설명
`prompt`	예	문자열	화면 설명
`aspect_ratio`	아니오	`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `auto`	기본값 `1:1`
`resolution`	아니오	`1k`, `2k`	기본값 `1k`
`quality`	아니오	`low`, `medium`	기본값 `medium`; `medium`은 디테일이 더 좋고, `low`는 더 빠름

각 작업은 이미지 1장을 생성하며, 여러 장이 필요하면 여러 작업을 동시에 제출하세요. 위 표에 없는 필드나 값을 사용하면 400이 반환되며, 오류 메시지에 구체적인 필드가 표시됩니다.

온라인 체험과 API 두 가지 경로

온라인 체험 (1분)

텍스트→이미지 모델 페이지를 열고 로그인합니다.
프롬프트를 입력하고 화면 비율과 해상도를 선택합니다.
「실행」을 클릭하고, 작업 성공 후 생성 이미지를 확인하고 다운로드합니다.

API 연동 (5분)

콘솔에서 API Key를 생성합니다.
POST /v1/tasks로 작업을 제출합니다.
GET /v1/tasks/<taskId>를 폴링하거나 콜백을 설정합니다.
성공 후 즉시 data.output[0].url을 다운로드합니다.

Product photography of a matte black ceramic coffee mug filled with steaming black coffee, thin wisps of steam curling upward, mug placed on a warm honey-toned wooden table near a bright window with sheer curtains, soft natural window light from the left creating gentle highlights on the mug's curved surface, shallow depth of field with the background softly blurred, plenty of empty negative space to the right of the mug for text overlay, warm cozy morning color grade, realistic commercial photography style, 3:2 aspect ratio

먼저 실행 가능한 프롬프트를 확보하세요: 아래 프롬프트는 3:2 제품 이미지입니다. 이 프롬프트로 생성하기 → (비율 3:2 선택, 해상도 2K 선택)

curl과 Python: 첫 이미지 생성하기

먼저 API Key를 설정합니다:

export HIAPI_API_KEY="sk-..."

모든 요청에는 Authorization: Bearer sk-<key>가 포함됩니다. 이미지 생성은 비동기이며, HiAPI의 다른 모델과 동일한 작업 인터페이스를 사용합니다.

1단계, 작업 생성:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": {
      "prompt": "A red apple on a wooden table, studio lighting, shallow depth of field",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

즉시 taskId가 반환됩니다:

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

2단계, 종료 상태까지 폴링:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JGSGB818MX59GVZZCVH67 \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status를 확인합니다: success는 성공, fail은 실패를 의미하며, 그 외 상태는 계속 기다립니다. 성공 응답 예시:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JGSGB818MX59GVZZCVH67-0.jpg",
        "artifactId": "76710",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

storage: "temp"와 expireAt에 유의하세요: 생성 이미지 주소는 임시이므로 작업 완료 후 즉시 다운로드하거나 자체 오브젝트 스토리지에 저장하세요.

Python 버전:

먼저 requests를 설치하고(python3 -m pip install requests) 위의 HIAPI_API_KEY를 설정하세요. 스크립트는 최대 10분 동안 폴링하며, 시간 초과 후에는 taskId를 보관하고 계속 조회하세요.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def generate_image(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = generate_image("A red apple on a wooden table, studio lighting", resolution="2k")
    print(url)

출시 전 유의사항은?

대량 처리에는 콜백을 사용하고, 타이트한 루프 폴링은 피하세요. 작업 생성 시 callback을 포함하면 작업 종료 후 HiAPI가 귀하의 주소로 푸시합니다:
```
{
  "model": "grok-imagine-image-2.0/text-to-image",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}
```
when: "final"은 작업이 성공 또는 실패 종료 상태에 도달했을 때 알림을 보내며, 수신 측은 taskId로 중복 제거합니다. 대화형 페이지에는 폴링, 배치 처리에는 콜백을 사용하세요.
생성 이미지를 즉시 저장하세요. data.output[0].url은 임시 주소이며 expireAt에 따라 만료됩니다.
작업은 한 번만 제출하세요. 응답을 받은 후 taskId와 비즈니스 작업의 대응 관계를 저장하세요. 중복 제출하면 여러 작업이 생성되어 각각 과금될 수 있습니다. 생성 요청이 시간 초과되어 ID를 받지 못한 경우, 먼저 작업 기록을 확인한 후 재제출 여부를 결정하세요.
resolution을 명시하세요. 기본값은 1k입니다. 1K와 2K는 동일 가격이므로 최종 결과물에는 "resolution": "2k"를 직접 전달하세요.
프롬프트 조정 시 quality: low를 사용하세요. 동일 가격에 반환 속도가 더 빠르며, 확정 후 medium으로 전환하세요.
오류 처리. 먼저 HTTP 상태와 응답의 code, message를 확인한 후 data를 읽으세요. 파라미터 또는 인증 오류는 수정 후 다시 제출해야 하며, 작업이 fail을 반환하면 오류를 기록하고 폴링을 중단하세요.

자주 묻는 질문

모델 ID는 어떻게 작성하나요? 전체 grok-imagine-image-2.0/text-to-image를 작성하고, 버전 번호 2.0과 /text-to-image를 유지하세요.

"additional properties not allowed" 오류가 발생하면? input은 prompt, aspect_ratio, resolution, quality 네 개 필드만 허용합니다. 다른 모델에서 흔히 쓰는 size, n, seed, negative_prompt, output_format은 여기서 사용할 수 없으므로 삭제하세요.

한 번에 여러 장을 생성할 수 있나요? 아니요, 각 작업은 1장을 생성합니다. 여러 장이 필요하면 여러 작업을 동시에 제출하세요.

출력 주소는 얼마나 유효한가요? 임시 저장소이며, 응답의 expireAt는 Unix 타임스탬프입니다. 작업 성공 후 즉시 다운로드하거나 저장하세요.

결과를 동기적으로 기다려야 하나요? 아니요. 생성 인터페이스는 작업이 큐에 들어간 후 즉시 반환됩니다. 짧은 스크립트에는 GET /v1/tasks/<taskId>를 폴링하고, 프로덕션 환경에서는 callback을 설정하세요.

실패한 작업도 과금되나요? 아니요, 성공적으로 생성된 이미지 기준으로 과금되며 실패 시 자동 환불됩니다. data.status가 fail이면 폴링을 중단하세요.

지금 바로 첫 이미지 생성하기

먼저 HIAPI_API_KEY를 설정하고, 위의 curl로 작업을 생성한 후 반환된 data.taskId로 조회하세요. 작업 성공 후 data.output[0].url에서 다운로드합니다. 먼저 결과를 보고 싶다면 텍스트→이미지 모델 페이지 열기를 클릭하세요. 가입 시 지급되는 200 크레딧으로 1장을 생성할 수 있습니다.