# Grok Imagine Image — /images/generations

xAI Grok Imagine Image(표준 등급) 기반의 이미지 생성 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는 보통 5~10초에 출력됩니다. 표준 등급의 편집은 원본 이미지의 비율을 유지하며, 다른 비율을 고르면 가운데를 잘라 냅니다. 1K와 2K는 같은 가격이며 실패한 요청은 과금하지 않습니다.

**엔드포인트:** `POST https://nezhagate.com/v1/images/generations`

## 인증
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 요청 본문
| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `model` | string | 예 | 모델 ID. 여기서는 grok-imagine-image입니다. |
| `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는 제공하지 않으며 지정하면 거절됩니다. |

## 요청 예시
```bash
# 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", "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'
```

## 응답
```json
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "grok-imagine-image"
}
```

## 이미지-투-이미지
이미지-투-이미지: 참조 이미지를 `image`에 넣으면(공개 URL, data: URI, 원시 base64 모두 가능) 원본의 정체성을 유지한 채 i2i가 실행됩니다 — 모델이 지정한 크기/비율로 다시 생성합니다. /v1/images/edits 호출과 동일합니다.

```bash
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "grok-imagine-image", "prompt": "change the background to a starry sky", "image": "https://example.com/ref.png", "size": "3:4"}'
```

## 이미지 작업 (제출 → 결과 폴링)
이미지 생성은 보통 1~3분이 걸리므로 이미지 엔드포인트는 작업(job) 방식만 사용합니다. 요청을 제출하면 즉시 작업 ID가 반환되고(HTTP 202), 그 ID로 결과를 폴링합니다 — 서버는 재시작 중에도 렌더링을 이어가므로 이미지가 사라지지 않습니다. 텍스트-투-이미지와 이미지-투-이미지 모두 같습니다. (기존의 "async": true 필드는 더 이상 필요하지 않으며, 받아들이되 무시합니다.)

```bash
# 1단계 — 작업 제출 (즉시 작업 ID 반환, HTTP 202)
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "grok-imagine-image", "prompt": "an ink-wash poster", "size": "3:4"}'
# 2단계 — 결과 폴링 (status가 succeeded가 될 때까지 2~3초 간격)
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

status는 queued / processing / succeeded / failed 중 하나입니다. 성공하면 응답에 data[].url이 담깁니다. 작업은 이를 생성한 계정만 조회할 수 있습니다. 이미지 엔드포인트는 항상 비동기이며 — 제출 시 작업 ID를 반환합니다. "async": true는 하위 호환을 위해 받아들이지만 무시됩니다.