Grok Imagine 이미지 API: curl·Python으로 첫 이미지 생성

Grok Imagine 이미지 API는 xAI 생성 엔드포인트에 prompt와 모델 ID를 보내고 반환된 이미지를 저장하는 방식으로 사용합니다. 출력 한 장과 명시적인 설정으로 시작해 응답을 확인한 다음 배치나 편집 기능을 추가하세요.

예시는 xAI 직접 API와 grok-imagine-image-2.0을 대상으로 합니다. 2026년 9월 8일 확인한 공식 생성 문서에 근거하며, 유료 생성을 실행한 테스트가 아닙니다. 권한이 있는 키, 서버 실행 환경, 이미지 저장소가 필요합니다. 확인 당시 Ofox에는 Grok Imagine이 등록되지 않았고 Ofox 키는 직접 요청에 사용할 수 없습니다.

curl로 한 장 요청하기

프로젝트의 비밀 정보 관리 방식으로 XAI_API_KEY를 설정하고 서버나 터미널에서 실행합니다. 실행하면 API 요금이 발생합니다. 공개 브라우저 코드에 키를 포함하지 마세요.

curl --fail-with-body --silent --show-error \
  --max-time 180 \
  https://api.x.ai/v1/images/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Studio photograph of a matte blue ceramic cup on a pale stone shelf, soft light from the left, no lettering",
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "response_format": "url"
  }' \
  -o grok-image-response.json

prompt는 예시 작업 지시이며 실험으로 선정한 최적 문구가 아닙니다. 180초 제한은 클라이언트 설정으로, 공급자가 보장하는 생성 시간이 아닙니다. 명령 종료 상태와 JSON을 먼저 확인하세요. 원본 응답을 남기면 오류 객체를 이미지 URL로 착각해 다운로드하는 문제를 피할 수 있습니다.

Python으로 이미지 바이트 저장하기

프로젝트 환경에 requests를 설치합니다. 다음 예시는 base64 응답을 요청하고 이미지 데이터가 있는지 확인한 뒤 바이트를 저장합니다.

import base64
import os
from pathlib import Path

import requests

payload = {
    "model": "grok-imagine-image-2.0",
    "prompt": (
        "Studio photograph of a matte blue ceramic cup on a pale "
        "stone shelf, soft light from the left, no lettering"
    ),
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "response_format": "b64_json",
}
response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    json=payload,
    timeout=(10, 180),
)
response.raise_for_status()
body = response.json()
images = body.get("data", [])
if not images or not images[0].get("b64_json"):
    raise RuntimeError("No base64 image returned; inspect response metadata")
image_bytes = base64.b64decode(images[0]["b64_json"], validate=True)
# Keep raw bytes until your image decoder identifies the returned format.
output = Path("grok-image-output.bin")
output.write_bytes(image_bytes)
print(f"Saved {len(image_bytes)} bytes to {output}")

.bin은 형식을 추측하지 않기 위한 확장자입니다. 실제 앱에서는 이미지 디코더로 형식과 크기를 확인한 후 올바른 확장자와 미디어 유형으로 저장하세요.

URL 응답도 지원하지만 주소는 임시입니다. 계속 보관할 이미지는 신속하게 자신의 저장소에 옮겨야 합니다. 응답 형식 설명을 참고하세요.

배치 전에 설정과 기록 정하기

목표 화면 비율, 예산상 화질, 출력 수를 먼저 정합니다. 각 생성에 다음 정보를 남기면 추적이 가능합니다.

생성과 편집은 별도 작업으로 설계하세요. 편집은 입력 이미지와 별도 요청 구조, 예산이 필요합니다. 생성 요청에 임의로 image 필드를 더한다고 모든 API가 인식하는 것은 아닙니다. 편집 문서를 확인하세요.

재시도 전에 오류 위치 확인하기

연결 실패, HTTP 오류, 성공 응답의 예상 밖 내용을 구분합니다. 인증 오류라면 목적지 호스트와 키 발급처를 확인하고, 검증 오류라면 요청을 최소화한 뒤 거부된 매개변수를 문서와 비교합니다.

전송 후 네트워크 시간이 초과되면 서버 생성 완료 여부를 클라이언트가 모를 수 있습니다. 확인 없이 유료 작업을 자동 반복하지 마세요. 작업 기록에 응답 메타데이터를 남기고 재전송을 명시적으로 처리하되 Authorization 헤더는 기록하지 않습니다.

콘텐츠 검토 관련 응답은 해당 규칙을 확인해 요청을 조정합니다. 반복 호출이 지원되지 않는 요청을 해결하지는 않습니다. 일반적인 문제는 이미지 생성 오류 가이드를 참고할 수 있지만, 매개변수 이름은 실제 공급자 문서에서 가져오세요.

기존 앱에 넣기

공급자 고유 필드는 작은 어댑터에 모으고, 나머지 앱은 prompt, 참조 소재, 출력 모양을 다루도록 구성합니다. 같은 제작 요구를 유지하면서 어댑터만 바꾸어 비교하기 쉬워집니다. FLUX API 흐름도 경계를 설계하는 참고 자료입니다.

호출량을 늘리기 전에 Image 2.0 예산을 계산하세요. 이전 별칭을 사용했다면 quality 모델 이전도 확인해야 합니다.