# Images & Video API

> OpenAI-compatible image generation and Grok Imagine video routes, model ids, and published flat prices.

Authenticate with `Authorization: Bearer $SCALEMAX_API_KEY`. Match the billing surface: credit keys use `https://api.scalemax.pro/v1`; token keys use `https://api.scalemax.pro/token/v1`. Image models appear in `GET /v1/models` with `family: "image"`. Video models use `family: "video"` when listed.

## Image model ids and prices

Flat per-image pricing by quality tier (same rates as ScaleMax Image 2). Token keys debit the derived token units at the published $2.50 = 1M rate. Keys other than Claude, Codex and combined keys pay 2x these image prices.

| Model id | Low | Medium | High |
| --- | --- | --- | --- |
| `grok-imagine-image` | $0.009 | $0.0795 | $0.3165 |
| `grok-imagine-image-quality` | $0.009 | $0.0795 | $0.3165 |
| Also published: `gemini-3.1-flash-image`, `flux-2-*`, `gpt-image-*` — see [the live catalog](https://dashboard.scalemax.pro/models) or `GET /v1/models`. |  |  |  |

### POST `/v1/images/generations`

OpenAI-compatible image generation. Returns a synchronous JSON body with image URLs or base64 data.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `model` | string | yes | One of the published image model ids. |
| `prompt` | string | yes | Text prompt. |
| `n` | integer | no | Batch size up to the model limit (Grok Imagine: 4). |
| `size` | string | no | Pixel size or aspect ratio (Grok Imagine accepts 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto). |
| `quality` | string | no | low \| medium \| high (selects the flat tier). |

**macOS / Linux**

image-generate.sh:

```bash
curl -X POST "https://api.scalemax.pro/v1/images/generations" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-image","prompt":"A red circle on white","size":"1:1","quality":"medium","n":1}'
```

**Windows PowerShell**

image-generate.ps1:

```powershell
@'
{"model":"grok-imagine-image","prompt":"A red circle on white","size":"1:1","quality":"medium","n":1}
'@ | Set-Content -Path body.json

curl.exe -X POST "https://api.scalemax.pro/v1/images/generations" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

PowerShell changes quotes inside a JSON argument, so the request body goes into body.json first and curl.exe sends that file. Type curl.exe, not curl: in Windows PowerShell 5.1, curl is a different command.

### POST `/v1/images/edits`

Edit an existing image. Grok Imagine models accept a reference image URL or upload (model-dependent).

## Video model ids and prices

Priced per clip by length and resolution. The prices below are for a 6-second 720p clip; a clip costs that price × seconds ÷ 6 × 0.7 at 480p, 1.0 at 720p or 1.6 at 1080p, rounded up. A request with no`resolution` is generated and billed at 720p. The full price is reserved before the job starts, and a key that cannot cover it gets a `402` naming the amount needed. Trial keys can make one 480p clip of up to 6 seconds on `grok-imagine-video`. Duration 1–15 seconds. 1080p is `grok-imagine-video-1.5` only. Edit is `grok-imagine-video` only. Extend is not available on the current hop.

| Model id | Credit price (6 s, 720p) | Token units (6 s, 720p) | Notes |
| --- | --- | --- | --- |
| `grok-imagine-video` | $0.25 | 250,000 | Text-to-video and image-to-video. 480p and 720p. Edit supported. 1080p and extend are not available on this model. |
| `grok-imagine-video-1.5` | $0.375 | 375,000 | Text-to-video and image-to-video. 480p, 720p, and 1080p. Edit and extend are not available on this model. |

Seedance and Kling are priced per second at each resolution: a clip costs that rate × seconds. Video tokens are 1 per micro-dollar, so a $1.00 clip debits 1,000,000 tokens from a pack. These models make video from text only (no input image, edit or extend). Seedance takes 4–15 seconds, Kling 3–15.

| Model id | Price per second | Notes |
| --- | --- | --- |
| `seedance-2.0` | 480p $10.40 · 720p $12.40 · 1080p $22.00 | Text-to-video, 4 to 15 seconds. 480p, 720p and 1080p. Priced per second. |
| `seedance-2.5` | 480p $11.60 · 720p $16.00 · 1080p $24.00 | Text-to-video, 4 to 15 seconds. 480p, 720p and 1080p. Priced per second. |
| `kling-v3` | 720p $3.20 · 1080p $4.16 · 4k $9.60 | Text-to-video, 3 to 15 seconds. 720p, 1080p and 4K. Priced per second. |
| `kling-v3-turbo` | 720p $3.84 · 1080p $4.80 | Faster text-to-video, 3 to 15 seconds. 720p and 1080p. Priced per second. |

## Video routes

Native video generation is async: create returns `202` with a task id, poll until `status` is terminal, then download from the ScaleMax `url` field (never a third-party host). Completed jobs include usage with `total_tokens` and `frontend_cost_microusd`.

### POST `/v1/videos/generations`

Start text-to-video or image-to-video generation.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `model` | string | yes | grok-imagine-video or grok-imagine-video-1.5. |
| `prompt` | string | yes | Scene description. |
| `image` | string \| object | no | Optional first-frame image for image-to-video on either model. |
| `aspect_ratio` | string | no | 1:1, 16:9, 9:16, 4:3, or 3:4. |
| `resolution` | string | no | 480p or 720p on grok-imagine-video; 480p, 720p, or 1080p on grok-imagine-video-1.5. Default 720p. Changes the price (0.7x / 1.0x / 1.6x). An unsupported value is a 400, not a silent drop. |
| `duration` | integer | no | 1–15; default 6. duration_seconds is accepted as an alias. |

### POST `/v1/videos/edits`

Edit an existing clip with a new prompt. `grok-imagine-video` only. `grok-imagine-video-1.5` returns 400.

### POST `/v1/videos/extensions`

Route exists. The current Imagine hop rejects extend (HTTP 405). Do not call it.

### GET `/v1/videos/:id`

Poll task status and progress. Optional `?wait=0..20` long-poll seconds.

### GET `/v1/videos/:id/content`

Stream the finished mp4. Supports `Range` after the task completes.

**macOS / Linux**

video-generate.sh:

```bash
curl -X POST "https://api.scalemax.pro/v1/videos/generations" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video","prompt":"Ocean waves at sunset","aspect_ratio":"16:9","duration":6}'
```

**Windows PowerShell**

video-generate.ps1:

```powershell
@'
{"model":"grok-imagine-video","prompt":"Ocean waves at sunset","aspect_ratio":"16:9","duration":6}
'@ | Set-Content -Path body.json

curl.exe -X POST "https://api.scalemax.pro/v1/videos/generations" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

PowerShell changes quotes inside a JSON argument, so the request body goes into body.json first and curl.exe sends that file. Type curl.exe, not curl: in Windows PowerShell 5.1, curl is a different command.

## Key scope

- Credit keys: any general-purpose scope may call every image and video model.
- Token keys on Claude, OpenAI, combined, Gemini, GLM, Local, and Qwen packs may call every published image model and every published video model.
- `grok-imagine-image*` and `grok-imagine-video*` are also on every other general-purpose key (DeepSeek, MiMo, Grok, reseller, …). Auto API and Voice keys cannot. Grok / DeepSeek / MiMo / reseller token packs still cannot call Azure or Qwen image models.