# GeiliAPI Grok Imagine — LLM integration spec

Human docs: https://sub.geiliapi.com/docs/grok-imagine.html
Web studio: https://sub.geiliapi.com/image-studio/  (engine: Grok Imagine)

Use this file to implement a client. Do not put `grok-imagine*` into Grok CLI or other chat CLIs. Grok CLI is chat-only.

## Auth and group

Create the key in https://sub.geiliapi.com → API 密钥 → group **Grok（Heavy）**.

Plain Grok group is chat-only. GPT Image 1K / 2K4K keys cannot call Grok Imagine. Codex / Claude / Gemini keys cannot call `/v1/videos/*`.

Header: `Authorization: Bearer <KEY>`

## Base URLs

- Image and video (long requests): `https://image-direct.geiliapi.com/v1`
- Models / key management: `https://sub.geiliapi.com/v1`
- Never send image/video jobs to `sub.geiliapi.com` (Cloudflare ~125s idle timeout → HTTP 524).
- `image-direct.geiliapi.com` bypasses Cloudflare, nginx timeout 600s.

Anonymous `POST https://image-direct.geiliapi.com/v1/images/generations` and `/v1/videos/generations` must return 401.

## Models

| Capability | model | Notes |
|---|---|---|
| Text-to-image (quality, default) | grok-imagine | Gateway maps to upstream grok-imagine-image-quality |
| Text-to-image (faster) | grok-imagine-image | Speed over quality |
| Image-to-image | grok-imagine-edit | `/v1/images/edits`, ≥1 reference image |
| Text-to-video | grok-imagine-video | 480p / 720p, duration 1–15s, default 8s |
| Image-to-video | grok-imagine-video-1.5 | Requires a reference image; 1080p allowed. Without an image the gateway rewrites to grok-imagine-video |

Do not send OpenAI `quality`. Send `resolution` (`1k` / `2k` / `4k`) for output clarity. Send `size` (`1024x1024` / `2048x2048` / `3840x2160`) for this site's 1K / 2K / 4K billing; the gateway strips `size` before upstream. Official xAI docs currently list `1k` and `2k`; `4k` is still accepted by the studio and billed at the group 4K price, but upstream may reject it.

Group fallback prices: 1K $0.05, 2K $0.08, 4K $0.10. Logged-in studio reads `/api/v1/groups/available`.

## Text-to-image

`POST https://image-direct.geiliapi.com/v1/images/generations`
`Content-Type: application/json`

```json
{
  "model": "grok-imagine",
  "prompt": "a cat on a rooftop watching the moon, cinematic night",
  "n": 1,
  "resolution": "1k",
  "size": "1024x1024"
}
```

## Image-to-image

`POST https://image-direct.geiliapi.com/v1/images/edits`
`multipart/form-data`

Fields:
- `model=grok-imagine-edit`
- `prompt=...`
- `resolution=1k` / `2k` / `4k`
- `size=1024x1024` / `2048x2048` / `3840x2160` (billing only)
- first file: `image`
- extra files: `image[1]`, `image[2]`, ...

## Text-to-video (async)

`POST https://image-direct.geiliapi.com/v1/videos/generations`
`Content-Type: application/json`

```json
{
  "model": "grok-imagine-video",
  "prompt": "waves hitting rocks, slow motion",
  "resolution": "720p",
  "duration": 8
}
```

Poll `GET https://image-direct.geiliapi.com/v1/videos/{request_id}` until `status` is `completed` / `done` / `success`.
Then use `video_url`, or `GET /v1/videos/{id}/content`.

`resolution`: `480p` | `720p` only.
`duration`: integer 1–15, default 8.
Video price = group per-second rate × duration.

## Image-to-video (async)

Same submit/poll endpoints. Reference image goes in `image.url` (`https://` or `data:image/...`). Prefer `720p` or `1080p`. Studio accepts 1 reference image.

```json
{
  "model": "grok-imagine-video-1.5",
  "prompt": "the person turns their head slightly, hair moving in the wind",
  "resolution": "1080p",
  "duration": 8,
  "image": {
    "url": "data:image/png;base64,..."
  }
}
```

If you omit the image, the gateway rewrites `grok-imagine-video-1.5` to `grok-imagine-video`. Do not treat that as image-to-video billing or 1080p.

## Response / verification

Image responses are OpenAI-compatible `data[]` with `url` or `b64_json`.
After a paid success, console「使用记录」must show the Grok（Heavy）key and a `grok-imagine*` model.

## Errors

- Engine locked / 401 / 404 / “Videos API is not supported”: wrong group or not Heavy
- 524: request hit `sub.geiliapi.com`
- Image-to-video billed as text-to-video: missing reference image
- 4K image rejected: official docs currently list `1k`/`2k`; retry with `2k`

Pricing: https://sub.geiliapi.com/model-pricing/
Updated: 2026-09-02