xAI Grok Imagine Image Quality(고품질 등급) 기반의 이미지 생성 API(비동기 작업)입니다. 디테일, 구도, 이미지 속 글자가 표준 등급보다 안정적입니다. 텍스트 기반 생성은 prompt만 있으면 되고, 편집은 참고 이미지를 image 또는 images(URL, data:, base64)에 넣거나 /v1/images/edits를 호출하며, 편집도 선택한 비율로 출력합니다. 제출하면 바로 작업 id(HTTP 202)가 반환되며 GET /v1/images/jobs/{id}를 폴링해 이미지를 받습니다. 일곱 가지 비율과 1K / 2K 두 가지 해상도를 지원합니다(2K는 resolution: "2K" 또는 2048급 크기 지정, 네이티브 렌더링. 4K는 제공하지 않아 제출 시 거절됩니다). 1K와 2K는 같은 가격이며 실패한 요청은 과금하지 않습니다.
플레이그라운드에서 사용해 보기 →인증
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
콘솔에서 API 키를 만들면 시작할 수 있습니다.
요청 본문
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | 모델 ID. 여기서는 grok-imagine-image-quality입니다. |
| prompt | string | 예 | 만들 이미지를 설명하는 텍스트 프롬프트. |
| size | string | 아니오 | 출력 화면 비율. 비율을 넘기는 방식을 권장합니다 — 1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9 — 이렇게 하면 모델이 그 비율로 네이티브 렌더링해 피사체가 잘리지 않습니다. 픽셀 크기(예: 1024x1024, 1024x1536, 1536x1024)도 받습니다. 기본값은 1:1(정사각형)입니다. |
| n | integer | 아니오 | 이미지 장수. 기본값 1. |
| image | string | 아니오 | 이미지-투-이미지: 참조 이미지를 공개 URL, data: URI, 또는 원시 base64로 넣습니다. 값이 있으면 선택한 크기 / 비율에서 원본의 정체성을 유지하는 진짜 이미지-투-이미지가 실행되며, /v1/images/edits 호출과 동일합니다. |
| images | array | 아니오 | 다중 이미지 참조(최대 8장. 피사체 일관성을 위해서는 4장 이하 권장): 문자열 배열이나 [{"image_url": "..."}] 객체 배열로 넘기세요. 각 항목은 공개 URL, data: URI, base64 모두 가능합니다. 여러 참조의 피사체와 화풍을 융합하는 다중 참조 이미지-투-이미지가 실행되며, /v1/images/edits의 다중 이미지 입력과 동일합니다. 참조가 한 장이라면 위의 image 필드를 써도 됩니다. |
| resolution | string | 아니오 | 해상도: 1K(기본값) 또는 2K이며 가격은 같습니다. size에 2048급 픽셀 크기를 지정해도 2K가 됩니다. 4K는 제공하지 않으며 지정하면 거절됩니다. |
요청 예시
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "grok-imagine-image-quality", "prompt": "a serene ink-wash poster, lots of negative space", "size": "1024x1536"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'응답
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "queued",
"model": "grok-imagine-image-quality"
}이미지-투-이미지
이미지-투-이미지: 참조 이미지를 `image`에 넣으면(공개 URL, data: URI, 원시 base64 모두 가능) 원본의 정체성을 유지한 채 i2i가 실행됩니다 — 모델이 지정한 크기/비율로 다시 생성합니다. /v1/images/edits 호출과 동일합니다.
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "grok-imagine-image-quality", "prompt": "배경을 별이 가득한 밤하늘로 바꿔 줘", "image": "https://example.com/ref.png", "size": "3:4"}'이미지 작업 (제출 → 결과 폴링)
이미지 생성은 보통 1~3분이 걸리므로 이미지 엔드포인트는 작업(job) 방식만 사용합니다. 요청을 제출하면 즉시 작업 ID가 반환되고(HTTP 202), 그 ID로 결과를 폴링합니다 — 서버는 재시작 중에도 렌더링을 이어가므로 이미지가 사라지지 않습니다. 텍스트-투-이미지와 이미지-투-이미지 모두 같습니다. (기존의 "async": true 필드는 더 이상 필요하지 않으며, 받아들이되 무시합니다.)
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "grok-imagine-image-quality", "prompt": "여백이 넉넉한 수묵화 포스터", "size": "3:4"}'{ "id": "img_3f9a...c2", "object": "image.generation.job", "status": "queued", "model": "grok-imagine-image-quality" }curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "succeeded",
"model": "grok-imagine-image-quality",
"data": [{ "url": "https://img.nezhagate.com/i/9f86d081a8....png" }]
}🕑 data[0].url은 저희 이미지 호스팅 링크로, 60일간 보관된 뒤 자동으로 삭제됩니다. 계속 쓰려면 다운로드해서 직접 운영하는 저장소나 CDN에 저장하세요.
status는 queued / processing / succeeded / failed 중 하나입니다. 성공하면 응답에 data[].url이 담깁니다. 작업은 이를 생성한 계정만 조회할 수 있습니다. 이미지 엔드포인트는 항상 비동기이며 — 제출 시 작업 ID를 반환합니다. "async": true는 하위 호환을 위해 받아들이지만 무시됩니다.
오류 코드
모든 오류 본문에는 error.message / error.type / error.code / error.param이 들어 있습니다. 분기는 code로 하세요. 전체 목록은 연동 가이드에 있습니다.
| HTTP | code | 설명 |
|---|---|---|
| 401 | invalid_api_key | API 키가 없거나 유효하지 않음 |
| 402 | insufficient_quota | 잔액 부족 또는 키 한도 초과 |
| 400 | invalid_request | 지원하지 않는 모델 또는 파라미터 |
| 429 | rate_limit_exceeded | 업스트림 요청 한도 초과 |
| 502 | upstream_error | 모든 업스트림 경로가 실패 |
