메인 콘텐츠로 건너뛰기
POST
Text-to-image: generate an image from a prompt (official channel)
🔒 신청 시 부여되는 GrokOfficial 그룹 필요: Grok Imagine Official은 Default 그룹에 포함되어 있지 않으므로, 호출하기 전에(이 페이지의 Playground 포함) 접근 권한을 신청해야 합니다. 접근 권한이 없거나 요청당 과금 Token을 사용하는 경우 모든 호출에서 503이 반환됩니다. 자세한 내용은 Grok Imagine Official 개요 - 그룹 설정을 참조하십시오.
우측의 인터랙티브 Playground를 통해 엔드포인트를 직접 테스트할 수 있습니다. Authorization에 API Key를 입력하고(형식: Bearer sk-xxx), prompt을 입력한 뒤 모델, resolution 및 aspect_ratio(2.0의 경우 quality 추가)을 선택하고 전송하십시오.
이 페이지를 사용하는 경우: 텍스트-투-이미지, 호출당 1장의 이미지. 이 채널은 아직 이미지 편집 기능을 제공하지 않습니다. 참조 기반 편집이나 호출당 여러 장의 이미지가 필요한 경우 Grok Imagine Reverse를 사용하십시오.
⚠️ 가장 흔히 발생하는 3가지 주의점
  1. size가 아닌 resolution을 사용하십시오: size은 해상도 티어에 매핑되지 않으므로 이미지는 기본값인 1k으로 생성되며 이에 따라 과금됩니다.
  2. 잘못된 입력 시 오류 반환: 범위를 벗어난 resolution / aspect_ratio은 422를 반환하고 quality: "high"은 400을 반환합니다. 이는 리버스 채널의 사일런트 폴백(silent fallback) 방식과 정반대입니다.
  3. 항상 n = 1로 전송하십시오: 여러 장의 이미지가 필요한 경우 여러 요청을 동시에 전송하십시오.
모든 이미지 API는 동기식입니다. 비동기 작업 ID가 없으므로 클라이언트 연결이 끊어지면 결과는 유실되지만 요청에 대한 과금은 정상적으로 진행됩니다. medium 및 2K 환경의 grok-imagine-image-2.0은 약 60~80초가 소요되므로 클라이언트 타임아웃을 360초로 설정하십시오. 자세한 내용은 이미지 API 주의 사항 및 모범 사례를 참조하십시오.

코드 예제

Python (OpenAI SDK)

Python (requests)

cURL

Node.js (fetch)

파라미터 빠른 참조

이미지당 가격(xAI와 동일):
모델 가격은 공식 사이트 기준에 맞춰 책정되며 변동 시 함께 조정될 수 있습니다. 위 표는 참고용일 뿐이며, 상단 내비게이션의 모델 가격 탭의 내용이 기준이 됩니다: 모델 가격.

응답 형식

  • data[]의 각 항목에는 response_format에 따라 url 또는 b64_json 중 하나가 포함됩니다.
  • 반환된 이미지 링크는 즉시 다운로드하십시오. 해당 링크를 계속해서 참조하지 마십시오.
  • usage은 자리표시자(prompt_tokens은 항상 1000 × image count)이며 대조 목적으로 사용할 수 없습니다 — 콘솔 과금 내역이 공식 기준입니다.
  • created은 항상 0이므로 시간 측정용으로 사용하지 마십시오.

관련 문서

인증

Authorization
string
header
필수

API Key from the APIYI console (Token group must include GrokOfficial)

본문

application/json
model
enum<string>
기본값:grok-imagine-image
필수

Model ID:

  • grok-imagine-image — standard, $0.02 per image at every resolution
  • grok-imagine-image-quality — high quality, $0.05 / $0.06 / $0.07 at 1k / 1.5k / 2k
  • grok-imagine-image-2.0 — newer model, low $0.04 / $0.05 / $0.06, medium $0.06 / $0.07 / $0.08
사용 가능한 옵션:
grok-imagine-image,
grok-imagine-image-quality,
grok-imagine-image-2.0
prompt
string
필수

Prompt in any language. Describe the subject, scene, style, and lighting in detail

예시:

"A photorealistic red wooden boat moored on a glassy alpine lake at dawn, mist over the water, snow-capped peaks behind, cinematic photography"

n
enum<integer>
기본값:1

Image count. Fixed at 1 on this channel; call concurrently for more images

사용 가능한 옵션:
1
resolution
enum<string>
기본값:1k

Resolution tier (lowercase), which also sets the price: 1k (default) / 1.5k / 2k.

Out-of-range values (such as 4k or 1K) return 422. Do not use size instead — it is not mapped to a resolution tier.

사용 가능한 옵션:
1k,
1.5k,
2k
aspect_ratio
enum<string>
기본값:1:1

Output aspect ratio, default 1:1. Measured examples: grok-imagine-image at 1k + 3:2 outputs 1248×832; -quality at 2k + 9:16 outputs 1584×2816.

Out-of-range values (such as 5:7) return 422.

사용 가능한 옵션:
1:1,
16:9,
9:16,
4:3,
3:4,
3:2,
2:3
quality
enum<string>

Quality tier, only for grok-imagine-image-2.0: low (default) or medium ($0.02 more per image, slower).

high returns 400. The other two models take no quality.

사용 가능한 옵션:
low,
medium
response_format
enum<string>
기본값:url

Response format: url (default; download and store the image right away) or b64_json (plain base64, no data: prefix)

사용 가능한 옵션:
url,
b64_json

응답

Image generated successfully

created
integer

Always 0; do not use it for timing

예시:

0

data
object[]

Image results (one item on this channel)

usage
object

Placeholder — do not reconcile with it. prompt_tokens is always 1000 × image count; the console billing records are authoritative