# LumeAPI Developer Documentation (machine-readable)

> OpenAI-compatible AI API gateway for text, image, and video.
> This file is intended for AI agents: fetch it to load the full developer reference.

- Portal docs index: /docs
- Per-model docs: /docs/models/{modelId}
- Gateway base URL: https://api.lumeapi.site/v1
- Auth: `Authorization: Bearer sk-…` (create keys in LumeAPI Console)
- Catalog API: `GET /api/models` on the LumeAPI portal backend

## Quick Start

1. Create an account and API key in the LumeAPI Console.
2. Set client base URL to `https://api.lumeapi.site/v1`.
3. Call chat/completions, images/generations, or videos with an exact catalog `model` id.
4. Top up USD wallet in Account when balance is low.

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-terra","messages":[{"role":"user","content":"Hello"}]}'
```

## Gateway Endpoints

- `POST /v1/chat/completions` — Text chat + Gemini/Nano Banana image models (Bearer sk-…)
- `GET /v1/chat/completions/stream/resume/{stream_id}` — Resume SSE stream after disconnect (last_event_id query or Last-Event-ID header) (Bearer sk-…)
- `POST /v1/images/generations` — Image generation (gpt-image-2, gpt-image-2-2k, seedream, grok-4-image, grok-4.2-image) — sync OpenAI JSON (Bearer sk-…)
- `POST /v1/images/edits` — Image edit (grok-4-image, grok-4.2-image) — multipart form, one reference image (Bearer sk-…)
- `POST /v1/videos` — Submit async video job — returns task id (Bearer sk-…)
- `GET /v1/videos/{id}` — Poll task status until completed or failed (Bearer sk-…)
- `GET /v1/videos/{id}/content` — Download MP4 when status=completed (Bearer sk-…)
- `GET /api/usage/balance/` — Account balance (USD) (Bearer sk-…)
- `GET /api/usage/pricing/` — Model pricing for your key (Bearer sk-…)

## Shared: Image integration

### 1. Base URL & auth
POST https://api.lumeapi.site/v1/images/generations or /v1/chat/completions with Authorization: Bearer sk-…. Obtain keys at the LumeAPI Console (/console). Catalog: GET /api/models on the LumeAPI portal API.

### 2. Model ids (exact match)
images/generations: gpt-image-2, gpt-image-2-2k, doubao-seedream-5.0, grok-4-image, grok-4.2-image. images/edits: grok-4-image, grok-4.2-image (multipart). chat/completions for Gemini Flash / Nano Banana: gemini-3.1-flash-image-preview, gemini-3.1-flash-image-preview-2k, google/gemini-3-pro-image-preview.

### 3. GPT Image 2 & Grok Image
One POST returns sync OpenAI { data: [{ url }] } after the gateway finishes (typically 30–90s). Do NOT poll /v1/tasks yourself. size = aspect ratio (16:9); 2K → model gpt-image-2-2k. With image_urls: pass reference images (gateway enforces max). Grok: aspect_ratio or size; resolution 1k|2k; quality low|medium|high; n 1–10. For Grok edits use POST /v1/images/edits with one image file. HTTP read timeout ≥ 180s.

### 4. Seedream & Gemini Flash
doubao-seedream-5.0: POST /v1/images/generations with aspect ratio size + resolution 2K (default). Sync { data: [{ url }] } after 30–90s. gemini-3.1-flash-image-preview*: POST /v1/chat/completions with modalities + image_config.

### 5. Billing & errors
Flat USD per image (see pricing tables). 402 insufficient_user_quota when balance empty. Failed generations return 4xx/5xx with error message.

### 6. If you still get task_id in ~0.3s
Contact support — success should be { data: [{ url }] } after 30–90s. Your request format is likely correct.

## Shared: Video integration

### Base URL
All requests go to https://api.lumeapi.site/v1 with Authorization: Bearer sk-…

### Three-step async flow
(1) POST /v1/videos → save id from response. (2) GET /v1/videos/{id} every 5–15s until status is completed or failed. (3) On completed, GET /v1/videos/{id}/content to download MP4.

### Use the gateway task id
Poll and download with the id returned by POST /v1/videos (e.g. task_Fk6QrnX6…). This is the only task id your client needs.

### Poll interval & timeout
Poll every 5–15 seconds with back-off. Typical completion: 30s–5min depending on model. Stop after 15–30 minutes if still not completed.

### Failed tasks are terminal
When status=failed, read error.message. Do not call /content. Submit a new POST /v1/videos to retry.

### Billing on submit
Balance is debited when POST /v1/videos returns 200. Poll until completed or failed before treating the job as successful.

### Video status map

- `queued`: Job accepted, waiting to start → Keep polling GET /v1/videos/{id}
- `in_progress`: Video is being generated → Keep polling; progress may increase
- `completed`: Ready to download → GET /v1/videos/{id}/content
- `failed`: Generation failed → Read error.message; submit a new job to retry

## Shared: Streaming

### Enable streaming
POST /v1/chat/completions with "stream": true. Response Content-Type is text/event-stream.

### SSE frame format
First line: retry: 3000 (reconnect delay ms). Each chunk: id: N then data: {JSON}. Heartbeats: : PING comment lines (~every 30s). End: data: [DONE].

### Save stream_id
Use the "id" field inside the first data JSON (e.g. chatcmpl-abc…) as stream_id for resume.

### Resume after disconnect
GET /v1/chat/completions/stream/resume/{stream_id}?last_event_id=N with the same Bearer key. Also accepts Last-Event-ID header. Replays cached chunks from N+1; waits for new chunks if still generating.

### 404 stream gone
Hub expired (>30 min after completion) or server restarted. Do not retry resume — re-submit POST or fetch final result another way.

### Video jobs
Video models use async POST/GET polling, not SSE. See Video Integration section.

## Reference media (by model family)

### Image

- **gpt-image-2 / gpt-image-2-2k** — POST /v1/images/generations; field `image_urls`; max Up to 16 (URL or base64 data URI). size = aspect ratio (16:9, 1:1, …). 2K → model gpt-image-2-2k. Gateway returns sync OpenAI { data: [{ url }] } (30–90s).
- **doubao-seedream-5.0** — POST /v1/images/generations; field `image`; max 1 (string) or multiple (string[]). size = aspect ratio; resolution 2K (default) | 3K | 4K. watermark optional. Legacy pixel size is mapped to ratio.
- **grok-4.2-image / grok-4-image** — POST /v1/images/generations · POST /v1/images/edits; field `aspect_ratio (generations) · image file (edits)`; max Edits: exactly 1 image file per request. Generations: prompt + aspect_ratio (or size) + resolution 1k|2k + quality + n (1–10). Edits: multipart form with image + prompt. Sync { data: [{ url }] }.
- **gemini-3.1-flash-image-preview / *-2k** — POST /v1/chat/completions; field `messages[].content[] image_url parts`; max Multiple images in one user message (OpenAI multimodal format). Put text and one or more {type:"image_url",image_url:{url:"…"}} parts in the user message. Use *-2k model id for 2K output tier.
- **google/gemini-3-pro-image-preview** — POST /v1/chat/completions; field `messages[].content[] image_url parts`; max Multiple images per message (multimodal). Same multimodal messages shape as Gemini Flash. Supports complex multi-image prompts for layout/branding edits.

### Video

- **seedance-2.0 / seedance-2.0-fast** — modes: T2V · first-frame I2V · first+last · multi-ref R2V · ref-video edit · multimodal; fields: image (1) · image+image_tail (2) · images[] (≤9) · video (+ ref_video_seconds) · video[]+images[]+audio[]; limits: 1 first frame · 2 first+last · up to 9 ref images (use @图1 in prompt) · +3 ref videos · +3 ref audio in multimodal. I2V: image only. First+last: image + image_tail. R2V: images array + prompt with @图N tags. Edit/extend: video URL + ref_video_seconds for billing.
- **kling-video-v3** — modes: T2V · first-frame I2V · first+last I2V; fields: image or image_urls (1) · image + image_tail (2); limits: 1 first frame · 2 with image_tail (last frame). Pass quality std|pro and duration 3–15s. image_urls alias maps to first frame.
- **kling-video-v3-omni** — modes: T2V · I2V · reference video / images / subjects; fields: image · image_tail · extra_body.video_list · extra_body.image_list · extra_body.element_list; limits: Multi ref via extra_body.* lists; ref video triggers omni ref-video pricing tier. Use kling-video-v3-omni when you need reference video or multi-subject control. Reference video via extra_body.video_list bills at std+ref / pro+ref USD/s.
- **grok-video** — modes: T2V · multi-image I2V; fields: image_urls[]; limits: Up to 7 public HTTPS URLs. Image-to-video. duration 6–30s integer. Output includes audio by default.
- **veo3.1-fast / veo3.1-quality** — modes: T2V · I2V / subject reference; fields: image_urls[] · generation_type; limits: Up to 3 · generation_type: frame (first/last) | reference (subject consistency). Fixed 8s output — do not pass duration/seconds. generate_audio is billing-tier only.
- **veo3.1-lite** — modes: T2V only; fields: —; limits: No reference images — prompt only. Fixed 8s text-to-video at economy per-second rates. Do not pass image_urls or images.
- **google/veo-3.1** — modes: T2V (primary); fields: —; limits: Text-only in current gateway mapping. Pass prompt, size/resolution, generate_audio. No image_urls in portal docs.
- **wan2.7** — modes: T2V · I2V first/last · video continuation; fields: image_urls[] · image_with_roles[] · video_urls[]; limits: 1 = first frame · 2 = first+last · video_urls: 1 URL (continuation, exclusive with images). No image/video → T2V. image_urls or image_with_roles → I2V. video_urls → continuation (no images/audio_url). Gateway maps image/images/image_url → image_urls.
- **viduq3-pro** — modes: T2V · I2V · first+last frame; fields: image_urls[]; limits: 0 = T2V · 1 = I2V start frame · 2 = first+last (gateway caps at 2). When image_urls set, omit aspect_ratio. Native audio on by default (audio:false for silent).
- **happyhorse-1.0-r2v** — modes: T2V · I2V · R2V · EDIT; fields: first_frame_image · image_urls[] · video_url; limits: I2V: 1 first_frame_image · R2V: 1–9 image_urls · EDIT: video_url + 0–5 style refs. Priority: video_url > first_frame_image > image_urls > prompt-only. EDIT bills by source video length (max 15s). Mutually exclusive except video_url + image_urls.

## Per-model documentation

Each subsection is the canonical developer doc for that model id.
Human UI: `/docs/models/{url-encoded-model-id}`

### Model: `claude-opus-4-7`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/claude-opus-4-7

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `claude-opus-4-8`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/claude-opus-4-8

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `claude-sonnet-4-6`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/claude-sonnet-4-6

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `deepseek/deepseek-v4-flash`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/deepseek%2Fdeepseek-v4-flash

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-flash",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `deepseek/deepseek-v4-pro`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/deepseek%2Fdeepseek-v4-pro

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-pro",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `doubao-seedream-5.0`

- Family: Image generations
- Endpoint: POST /v1/images/generations
- Docs page: /docs/models/doubao-seedream-5.0

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gpt-image-2-1k \| gpt-image-2-2k \| gpt-image-2 (legacy 1K alias) \| doubao-seedream-5.0 \| grok-4-image \| grok-4.2-image — exact catalog ids only |
| `prompt` | string | yes | Text description of the image |
| `size` | string | no | gpt-image-2-1k / gpt-image-2-2k: aspect ratio 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| … (or legacy WxH — gateway maps to ratio). gpt-image-2 (legacy alias for 1K). grok-4*: alias for aspect_ratio. doubao-seedream-5.0: aspect ratio + resolution 2K\|3K\|4K |
| `aspect_ratio` | string | no | grok-4-image / grok-4.2-image: 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | gpt-image-2-1k → 1k; gpt-image-2-2k → 2k; gpt-image-2 legacy alias → 1k (optional resolution extra for 4k). grok-4*: 1k (default) \| 2k. Prefer gpt-image-2-1k / gpt-image-2-2k. |
| `n` | integer | no | Images to generate. gpt-image-2: fixed 1. grok-4*: 1–10. Billed per successful image. |
| `quality` | string | no | grok-4*: low (default) \| medium \| high. Ignored for gpt-image-2. |
| `image_urls` | string[] | no | Img2img reference (gpt-image-2 only). Up to 16 URLs or data URIs (gateway may enforce lower limits). Grok: use POST /v1/images/edits instead. |
| `image` | string | string[] | no | Legacy alias — gateway maps to image_urls for gpt-image-2. seedream: still accepts image. |
| `strength` | number | no | Legacy img2img field — not used for gpt-image-2. |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Img2img (gpt-image-2)` | — | no | When image_urls or image is present, pass up to 5–16 reference URLs/data URIs (gateway enforces per-request limits). Prefer aspect-ratio size values such as 1:1 \| 16:9 \| 9:16. |
| `Gateway only` | — | no | Call ONLY https://api.lumeapi.site/v1 with your LumeAPI sk-… key. Do not call any third-party API host directly. |
| `Sync response` | — | no | GPT Image 2 & Grok Image: one HTTP response with standard OpenAI { data: [{ url }] } (30–90s typical). The gateway handles async work server-side. Do NOT call GET /v1/tasks/{id} on our gateway. |
| `Unexpected task_id` | — | no | If you get task_id back in ~0.3s with no url, contact support — your request format is likely correct; success looks like { data: [{ url }] } after 30–90s. |
| `2K tier` | — | no | Use model id gpt-image-2-2k (not gpt-image-2 + quality=high). |


#### Example

```bash
curl https://api.lumeapi.site/v1/images/generations \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0",
    "prompt": "Same product on a marble counter, soft studio lighting",
    "image": "https://cdn.example.com/product-reference.jpg",
    "size": "16:9",
    "resolution": "2K",
    "n": 1,
    "watermark": false
  }'
```

### Model: `gemini-3-flash`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gemini-3-flash

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `gemini-3.1-flash-image-preview`

- Family: Gemini / Nano Banana image via chat
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gemini-3.1-flash-image-preview

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gemini-3.1-flash-image-preview \| …-2k \| google/gemini-3-pro-image-preview |
| `messages` | array | yes | OpenAI multimodal messages. Text + optional image_url parts for edit/style reference. |
| `messages[].content[]` | object[] | no | [{type:"text",text:"…"},{type:"image_url",image_url:{url:"https://…"}}] — attach 1+ reference images |
| `image_config.image_size` | string | no | 2K tier: use *-2k model ids |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Keep the bottle layout; change background to sunset beach"},
        {"type": "image_url", "image_url": {"url": "https://cdn.example.com/ref.png"}}
      ]
    }]
  }'
```

### Model: `gemini-3.1-flash-image-preview-2k`

- Family: Gemini / Nano Banana image via chat
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gemini-3.1-flash-image-preview-2k

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gemini-3.1-flash-image-preview \| …-2k \| google/gemini-3-pro-image-preview |
| `messages` | array | yes | OpenAI multimodal messages. Text + optional image_url parts for edit/style reference. |
| `messages[].content[]` | object[] | no | [{type:"text",text:"…"},{type:"image_url",image_url:{url:"https://…"}}] — attach 1+ reference images |
| `image_config.image_size` | string | no | 2K tier: use *-2k model ids |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Keep the bottle layout; change background to sunset beach"},
        {"type": "image_url", "image_url": {"url": "https://cdn.example.com/ref.png"}}
      ]
    }]
  }'
```

### Model: `gemini-3.1-pro-preview`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gemini-3.1-pro-preview

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `gemini-3.5-flash`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gemini-3.5-flash

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `google/gemini-3-pro-image-preview`

- Family: Gemini / Nano Banana image via chat
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/google%2Fgemini-3-pro-image-preview

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gemini-3.1-flash-image-preview \| …-2k \| google/gemini-3-pro-image-preview |
| `messages` | array | yes | OpenAI multimodal messages. Text + optional image_url parts for edit/style reference. |
| `messages[].content[]` | object[] | no | [{type:"text",text:"…"},{type:"image_url",image_url:{url:"https://…"}}] — attach 1+ reference images |
| `image_config.image_size` | string | no | 2K tier: use *-2k model ids |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Keep the bottle layout; change background to sunset beach"},
        {"type": "image_url", "image_url": {"url": "https://cdn.example.com/ref.png"}}
      ]
    }]
  }'
```

### Model: `google/veo-3.1`

- Family: Veo 3.1 video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/google%2Fveo-3.1

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | google/veo-3.1 |
| `prompt` | string | yes | Video description |
| `size / resolution` | string | no | 1080p / 4K tiers for billing |
| `generate_audio / with_audio` | boolean | no | Audio tier multiplier |
| `duration / seconds` | integer | no | Output length in seconds |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Fixed duration` | — | no | All Veo 3.1 tier ids output 8 seconds — do not pass duration or seconds. |
| `veo3.1-lite` | — | no | Text-to-video only. Do not pass image_urls, images, or reference fields. |
| `veo3.1-quality` | — | no | Higher visual fidelity tier at premium per-second rates. Supports T2V and I2V like veo3.1-fast. |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "Cinematic ocean waves at golden hour",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

### Model: `gpt-5.4`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gpt-5.4

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `gpt-5.4-mini`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gpt-5.4-mini

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `gpt-5.5`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gpt-5.5

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `gpt-5.6-sol`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gpt-5.6-sol

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `gpt-5.6-terra`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/gpt-5.6-terra

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `gpt-image-2`

- Family: Image generations
- Endpoint: POST /v1/images/generations
- Docs page: /docs/models/gpt-image-2

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gpt-image-2-1k \| gpt-image-2-2k \| gpt-image-2 (legacy 1K alias) \| doubao-seedream-5.0 \| grok-4-image \| grok-4.2-image — exact catalog ids only |
| `prompt` | string | yes | Text description of the image |
| `size` | string | no | gpt-image-2-1k / gpt-image-2-2k: aspect ratio 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| … (or legacy WxH — gateway maps to ratio). gpt-image-2 (legacy alias for 1K). grok-4*: alias for aspect_ratio. doubao-seedream-5.0: aspect ratio + resolution 2K\|3K\|4K |
| `aspect_ratio` | string | no | grok-4-image / grok-4.2-image: 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | gpt-image-2-1k → 1k; gpt-image-2-2k → 2k; gpt-image-2 legacy alias → 1k (optional resolution extra for 4k). grok-4*: 1k (default) \| 2k. Prefer gpt-image-2-1k / gpt-image-2-2k. |
| `n` | integer | no | Images to generate. gpt-image-2: fixed 1. grok-4*: 1–10. Billed per successful image. |
| `quality` | string | no | grok-4*: low (default) \| medium \| high. Ignored for gpt-image-2. |
| `image_urls` | string[] | no | Img2img reference (gpt-image-2 only). Up to 16 URLs or data URIs (gateway may enforce lower limits). Grok: use POST /v1/images/edits instead. |
| `image` | string | string[] | no | Legacy alias — gateway maps to image_urls for gpt-image-2. seedream: still accepts image. |
| `strength` | number | no | Legacy img2img field — not used for gpt-image-2. |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Img2img (gpt-image-2)` | — | no | When image_urls or image is present, pass up to 5–16 reference URLs/data URIs (gateway enforces per-request limits). Prefer aspect-ratio size values such as 1:1 \| 16:9 \| 9:16. |
| `Gateway only` | — | no | Call ONLY https://api.lumeapi.site/v1 with your LumeAPI sk-… key. Do not call any third-party API host directly. |
| `Sync response` | — | no | GPT Image 2 & Grok Image: one HTTP response with standard OpenAI { data: [{ url }] } (30–90s typical). The gateway handles async work server-side. Do NOT call GET /v1/tasks/{id} on our gateway. |
| `Unexpected task_id` | — | no | If you get task_id back in ~0.3s with no url, contact support — your request format is likely correct; success looks like { data: [{ url }] } after 30–90s. |
| `2K tier` | — | no | Use model id gpt-image-2-2k (not gpt-image-2 + quality=high). |


#### Example

```bash
curl https://api.lumeapi.site/v1/images/generations \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A minimalist product photo of wireless earbuds on marble",
    "size": "16:9",
    "n": 1
  }'
```

### Model: `gpt-image-2-1k`

- Family: Image generations
- Endpoint: POST /v1/images/generations
- Docs page: /docs/models/gpt-image-2-1k

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gpt-image-2-1k \| gpt-image-2-2k \| gpt-image-2 (legacy 1K alias) \| doubao-seedream-5.0 \| grok-4-image \| grok-4.2-image — exact catalog ids only |
| `prompt` | string | yes | Text description of the image |
| `size` | string | no | gpt-image-2-1k / gpt-image-2-2k: aspect ratio 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| … (or legacy WxH — gateway maps to ratio). gpt-image-2 (legacy alias for 1K). grok-4*: alias for aspect_ratio. doubao-seedream-5.0: aspect ratio + resolution 2K\|3K\|4K |
| `aspect_ratio` | string | no | grok-4-image / grok-4.2-image: 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | gpt-image-2-1k → 1k; gpt-image-2-2k → 2k; gpt-image-2 legacy alias → 1k (optional resolution extra for 4k). grok-4*: 1k (default) \| 2k. Prefer gpt-image-2-1k / gpt-image-2-2k. |
| `n` | integer | no | Images to generate. gpt-image-2: fixed 1. grok-4*: 1–10. Billed per successful image. |
| `quality` | string | no | grok-4*: low (default) \| medium \| high. Ignored for gpt-image-2. |
| `image_urls` | string[] | no | Img2img reference (gpt-image-2 only). Up to 16 URLs or data URIs (gateway may enforce lower limits). Grok: use POST /v1/images/edits instead. |
| `image` | string | string[] | no | Legacy alias — gateway maps to image_urls for gpt-image-2. seedream: still accepts image. |
| `strength` | number | no | Legacy img2img field — not used for gpt-image-2. |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Img2img (gpt-image-2)` | — | no | When image_urls or image is present, pass up to 5–16 reference URLs/data URIs (gateway enforces per-request limits). Prefer aspect-ratio size values such as 1:1 \| 16:9 \| 9:16. |
| `Gateway only` | — | no | Call ONLY https://api.lumeapi.site/v1 with your LumeAPI sk-… key. Do not call any third-party API host directly. |
| `Sync response` | — | no | GPT Image 2 & Grok Image: one HTTP response with standard OpenAI { data: [{ url }] } (30–90s typical). The gateway handles async work server-side. Do NOT call GET /v1/tasks/{id} on our gateway. |
| `Unexpected task_id` | — | no | If you get task_id back in ~0.3s with no url, contact support — your request format is likely correct; success looks like { data: [{ url }] } after 30–90s. |
| `2K tier` | — | no | Use model id gpt-image-2-2k (not gpt-image-2 + quality=high). |


#### Example

```bash
curl https://api.lumeapi.site/v1/images/generations \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A minimalist product photo of wireless earbuds on marble",
    "size": "16:9",
    "n": 1
  }'
```

### Model: `gpt-image-2-2k`

- Family: Image generations
- Endpoint: POST /v1/images/generations
- Docs page: /docs/models/gpt-image-2-2k

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gpt-image-2-1k \| gpt-image-2-2k \| gpt-image-2 (legacy 1K alias) \| doubao-seedream-5.0 \| grok-4-image \| grok-4.2-image — exact catalog ids only |
| `prompt` | string | yes | Text description of the image |
| `size` | string | no | gpt-image-2-1k / gpt-image-2-2k: aspect ratio 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| … (or legacy WxH — gateway maps to ratio). gpt-image-2 (legacy alias for 1K). grok-4*: alias for aspect_ratio. doubao-seedream-5.0: aspect ratio + resolution 2K\|3K\|4K |
| `aspect_ratio` | string | no | grok-4-image / grok-4.2-image: 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | gpt-image-2-1k → 1k; gpt-image-2-2k → 2k; gpt-image-2 legacy alias → 1k (optional resolution extra for 4k). grok-4*: 1k (default) \| 2k. Prefer gpt-image-2-1k / gpt-image-2-2k. |
| `n` | integer | no | Images to generate. gpt-image-2: fixed 1. grok-4*: 1–10. Billed per successful image. |
| `quality` | string | no | grok-4*: low (default) \| medium \| high. Ignored for gpt-image-2. |
| `image_urls` | string[] | no | Img2img reference (gpt-image-2 only). Up to 16 URLs or data URIs (gateway may enforce lower limits). Grok: use POST /v1/images/edits instead. |
| `image` | string | string[] | no | Legacy alias — gateway maps to image_urls for gpt-image-2. seedream: still accepts image. |
| `strength` | number | no | Legacy img2img field — not used for gpt-image-2. |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Img2img (gpt-image-2)` | — | no | When image_urls or image is present, pass up to 5–16 reference URLs/data URIs (gateway enforces per-request limits). Prefer aspect-ratio size values such as 1:1 \| 16:9 \| 9:16. |
| `Gateway only` | — | no | Call ONLY https://api.lumeapi.site/v1 with your LumeAPI sk-… key. Do not call any third-party API host directly. |
| `Sync response` | — | no | GPT Image 2 & Grok Image: one HTTP response with standard OpenAI { data: [{ url }] } (30–90s typical). The gateway handles async work server-side. Do NOT call GET /v1/tasks/{id} on our gateway. |
| `Unexpected task_id` | — | no | If you get task_id back in ~0.3s with no url, contact support — your request format is likely correct; success looks like { data: [{ url }] } after 30–90s. |
| `2K tier` | — | no | Use model id gpt-image-2-2k (not gpt-image-2 + quality=high). |


#### Example

```bash
curl https://api.lumeapi.site/v1/images/generations \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-2k",
    "prompt": "Editorial fashion portrait, soft window light",
    "size": "3:4",
    "n": 1
  }'
```

### Model: `grok-4-image`

- Family: Grok image (generations + edits)
- Endpoint: POST /v1/images/generations · POST /v1/images/edits
- Docs page: /docs/models/grok-4-image

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gpt-image-2-1k \| gpt-image-2-2k \| gpt-image-2 (legacy 1K alias) \| doubao-seedream-5.0 \| grok-4-image \| grok-4.2-image — exact catalog ids only |
| `prompt` | string | yes | Text description of the image |
| `size` | string | no | gpt-image-2-1k / gpt-image-2-2k: aspect ratio 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| … (or legacy WxH — gateway maps to ratio). gpt-image-2 (legacy alias for 1K). grok-4*: alias for aspect_ratio. doubao-seedream-5.0: aspect ratio + resolution 2K\|3K\|4K |
| `aspect_ratio` | string | no | grok-4-image / grok-4.2-image: 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | gpt-image-2-1k → 1k; gpt-image-2-2k → 2k; gpt-image-2 legacy alias → 1k (optional resolution extra for 4k). grok-4*: 1k (default) \| 2k. Prefer gpt-image-2-1k / gpt-image-2-2k. |
| `n` | integer | no | Images to generate. gpt-image-2: fixed 1. grok-4*: 1–10. Billed per successful image. |
| `quality` | string | no | grok-4*: low (default) \| medium \| high. Ignored for gpt-image-2. |
| `model` | string | yes | grok-4-image \| grok-4.2-image |
| `prompt` | string | yes | Edit instruction describing desired changes |
| `image` | file | yes | Single reference image file (multipart field image or image[]) |
| `aspect_ratio` | string | no | 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | 1k (default) \| 2k |
| `quality` | string | no | low (default) \| medium \| high |
| `n` | integer | no | 1–10 images. Billed per successful image. |
| `response_format` | string | no | url (default) \| b64_json |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Multipart only` | — | no | POST /v1/images/edits with Content-Type: multipart/form-data. Exactly one image file per request. |
| `Sync response` | — | no | Returns standard OpenAI { data: [{ url }] } after the gateway finishes (typically 30–90s). HTTP read timeout ≥ 180s. |


#### Example

```bash
curl https://api.lumeapi.site/v1/images/generations \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.2-image",
    "prompt": "Watercolor village at dawn",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "quality": "medium",
    "n": 1
  }'
```

### Model: `grok-4.2-image`

- Family: Grok image (generations + edits)
- Endpoint: POST /v1/images/generations · POST /v1/images/edits
- Docs page: /docs/models/grok-4.2-image

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gpt-image-2-1k \| gpt-image-2-2k \| gpt-image-2 (legacy 1K alias) \| doubao-seedream-5.0 \| grok-4-image \| grok-4.2-image — exact catalog ids only |
| `prompt` | string | yes | Text description of the image |
| `size` | string | no | gpt-image-2-1k / gpt-image-2-2k: aspect ratio 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| … (or legacy WxH — gateway maps to ratio). gpt-image-2 (legacy alias for 1K). grok-4*: alias for aspect_ratio. doubao-seedream-5.0: aspect ratio + resolution 2K\|3K\|4K |
| `aspect_ratio` | string | no | grok-4-image / grok-4.2-image: 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | gpt-image-2-1k → 1k; gpt-image-2-2k → 2k; gpt-image-2 legacy alias → 1k (optional resolution extra for 4k). grok-4*: 1k (default) \| 2k. Prefer gpt-image-2-1k / gpt-image-2-2k. |
| `n` | integer | no | Images to generate. gpt-image-2: fixed 1. grok-4*: 1–10. Billed per successful image. |
| `quality` | string | no | grok-4*: low (default) \| medium \| high. Ignored for gpt-image-2. |
| `model` | string | yes | grok-4-image \| grok-4.2-image |
| `prompt` | string | yes | Edit instruction describing desired changes |
| `image` | file | yes | Single reference image file (multipart field image or image[]) |
| `aspect_ratio` | string | no | 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | 1k (default) \| 2k |
| `quality` | string | no | low (default) \| medium \| high |
| `n` | integer | no | 1–10 images. Billed per successful image. |
| `response_format` | string | no | url (default) \| b64_json |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Multipart only` | — | no | POST /v1/images/edits with Content-Type: multipart/form-data. Exactly one image file per request. |
| `Sync response` | — | no | Returns standard OpenAI { data: [{ url }] } after the gateway finishes (typically 30–90s). HTTP read timeout ≥ 180s. |


#### Example

```bash
curl https://api.lumeapi.site/v1/images/generations \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.2-image",
    "prompt": "Watercolor village at dawn",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "quality": "medium",
    "n": 1
  }'
```

### Model: `grok-4.3`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/grok-4.3

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `grok-video`

- Family: Grok video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/grok-video

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | grok-video |
| `prompt` | string | yes | Video description (Chinese or English) |
| `size` | string | no | 16:9 \| 9:16 \| 1:1 \| 3:2 \| 2:3. Alias: aspect_ratio. |
| `quality` | string | no | 480p (default) \| 720p |
| `duration` | integer | no | 6–30 seconds, integer only. Default 6. |
| `image_urls` | array | no | Public HTTPS URLs for image-to-video, max 7 |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Audio` | — | no | Grok Imagine 1.5 outputs video with sound by default. No with_audio / generate_audio field. Billed per second regardless. |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video",
    "prompt": "Gentle breeze moves the leaves, cinematic depth of field",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "size": "16:9",
    "duration": 6,
    "quality": "480p"
  }'
```

### Model: `happyhorse-1.0-r2v`

- Family: HappyHorse R2V video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/happyhorse-1.0-r2v

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | happyhorse-1.0-r2v — T2V / I2V / R2V / EDIT unified entry |
| `prompt` | string | no | Required for T2V/R2V/EDIT; optional but recommended for I2V |
| `first_frame_image` | string | no | I2V: first-frame image URL or base64 — mutually exclusive with image_urls/video_url |
| `image_urls` | string[] | no | R2V: 1–9 reference images; EDIT: 0–5 style refs with video_url |
| `video_url` | string | no | EDIT: source video URL (3–60s; >15s truncated). Mutually exclusive with first_frame_image |
| `resolution` | string | no | 720P \| 1080P (default) — affects billing |
| `duration` | integer | no | 3–15 seconds (default 5). Ignored in EDIT mode — bills by source video length (max 15s) |
| `size` | string | no | Aspect ratio: 16:9 \| 9:16 \| 1:1 \| 4:3 \| 3:4 — T2V/R2V only; ignored in I2V/EDIT |
| `audio_setting` | string | no | EDIT only: auto (default) \| origin — keep source audio track |
| `seed` | integer | no | 0–2147483647 for reproducibility |
| `watermark` | boolean | no | Default false |
| `ref_video_seconds` | number | no | EDIT billing hint when video_url is set (gateway uses min(source, 15)) |
| `Async flow` | — | no | POST /v1/videos → poll GET /v1/videos/{id} → GET /v1/videos/{id}/content when completed. |
| `Pricing` | — | no | 720p $0.15/s · 1080p $0.25/s × duration (all modes) |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Mode routing` | — | no | prompt only → T2V · first_frame_image → I2V · image_urls (1–9) → R2V · video_url → EDIT |
| `Priority` | — | no | video_url > first_frame_image > image_urls > prompt-only |
| `Mutual exclusion` | — | no | first_frame_image / image_urls / video_url are pairwise exclusive except video_url + image_urls (EDIT) |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-r2v",
    "prompt": "Product orbit shot on marble",
    "resolution": "1080P",
    "duration": 5,
    "size": "16:9"
  }'
```

### Model: `kling-video-v3`

- Family: Kling video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/kling-video-v3

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | kling-video-v3 \| kling-video-v3-omni |
| `prompt` | string | yes | Video description |
| `quality` | string | no | std (720p, default) \| pro (1080p). No 480p/4K — do not use resolution/size/fps. |
| `with_audio` | boolean | no | Generate audio track (default false) |
| `duration` | integer | no | 3–15 seconds. Default 5. |
| `aspect_ratio` | string | no | 1:1 \| 16:9 \| 9:16 |
| `image` | string | no | First-frame image URL (I2V). Alias: image_urls via gateway. |
| `image_tail` | string | no | Last-frame image URL (first+last frame I2V) |
| `extra_body.video_list` | array | no | Reference video (kling-video-v3-omni only) |
| `extra_body.image_list` | array | no | Reference images (kling-video-v3-omni only) |
| `extra_body.element_list` | array | no | Reference subjects (kling-video-v3-omni only) |
| `extra_body.multi_shot` | boolean | no | Enable storyboard shots |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Quality` | — | no | quality std = 720p, pro = 1080p only (no 4K tier). |
| `Duration` | — | no | 3–15s, default 5. Billed per second × quality/audio/ref tier. |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-v3",
    "prompt": "Camera slowly pushes in, subject turns toward the window",
    "image": "https://cdn.example.com/first-frame.jpg",
    "quality": "std",
    "with_audio": false,
    "duration": 5,
    "aspect_ratio": "16:9"
  }'
```

### Model: `kling-video-v3-omni`

- Family: Kling video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/kling-video-v3-omni

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | kling-video-v3 \| kling-video-v3-omni |
| `prompt` | string | yes | Video description |
| `quality` | string | no | std (720p, default) \| pro (1080p). No 480p/4K — do not use resolution/size/fps. |
| `with_audio` | boolean | no | Generate audio track (default false) |
| `duration` | integer | no | 3–15 seconds. Default 5. |
| `aspect_ratio` | string | no | 1:1 \| 16:9 \| 9:16 |
| `image` | string | no | First-frame image URL (I2V). Alias: image_urls via gateway. |
| `image_tail` | string | no | Last-frame image URL (first+last frame I2V) |
| `extra_body.video_list` | array | no | Reference video (kling-video-v3-omni only) |
| `extra_body.image_list` | array | no | Reference images (kling-video-v3-omni only) |
| `extra_body.element_list` | array | no | Reference subjects (kling-video-v3-omni only) |
| `extra_body.multi_shot` | boolean | no | Enable storyboard shots |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Quality` | — | no | quality std = 720p, pro = 1080p only (no 4K tier). |
| `Duration` | — | no | 3–15s, default 5. Billed per second × quality/audio/ref tier. |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-v3",
    "prompt": "Camera slowly pushes in, subject turns toward the window",
    "image": "https://cdn.example.com/first-frame.jpg",
    "quality": "std",
    "with_audio": false,
    "duration": 5,
    "aspect_ratio": "16:9"
  }'
```

### Model: `qwen-image-2.0`

- Family: Image generations
- Endpoint: POST /v1/images/generations
- Docs page: /docs/models/qwen-image-2.0

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | gpt-image-2-1k \| gpt-image-2-2k \| gpt-image-2 (legacy 1K alias) \| doubao-seedream-5.0 \| grok-4-image \| grok-4.2-image — exact catalog ids only |
| `prompt` | string | yes | Text description of the image |
| `size` | string | no | gpt-image-2-1k / gpt-image-2-2k: aspect ratio 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| … (or legacy WxH — gateway maps to ratio). gpt-image-2 (legacy alias for 1K). grok-4*: alias for aspect_ratio. doubao-seedream-5.0: aspect ratio + resolution 2K\|3K\|4K |
| `aspect_ratio` | string | no | grok-4-image / grok-4.2-image: 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 (default 1:1). Alias: size. |
| `resolution` | string | no | gpt-image-2-1k → 1k; gpt-image-2-2k → 2k; gpt-image-2 legacy alias → 1k (optional resolution extra for 4k). grok-4*: 1k (default) \| 2k. Prefer gpt-image-2-1k / gpt-image-2-2k. |
| `n` | integer | no | Images to generate. gpt-image-2: fixed 1. grok-4*: 1–10. Billed per successful image. |
| `quality` | string | no | grok-4*: low (default) \| medium \| high. Ignored for gpt-image-2. |
| `image_urls` | string[] | no | Img2img reference (gpt-image-2 only). Up to 16 URLs or data URIs (gateway may enforce lower limits). Grok: use POST /v1/images/edits instead. |
| `image` | string | string[] | no | Legacy alias — gateway maps to image_urls for gpt-image-2. seedream: still accepts image. |
| `strength` | number | no | Legacy img2img field — not used for gpt-image-2. |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Img2img (gpt-image-2)` | — | no | When image_urls or image is present, pass up to 5–16 reference URLs/data URIs (gateway enforces per-request limits). Prefer aspect-ratio size values such as 1:1 \| 16:9 \| 9:16. |
| `Gateway only` | — | no | Call ONLY https://api.lumeapi.site/v1 with your LumeAPI sk-… key. Do not call any third-party API host directly. |
| `Sync response` | — | no | GPT Image 2 & Grok Image: one HTTP response with standard OpenAI { data: [{ url }] } (30–90s typical). The gateway handles async work server-side. Do NOT call GET /v1/tasks/{id} on our gateway. |
| `Unexpected task_id` | — | no | If you get task_id back in ~0.3s with no url, contact support — your request format is likely correct; success looks like { data: [{ url }] } after 30–90s. |
| `2K tier` | — | no | Use model id gpt-image-2-2k (not gpt-image-2 + quality=high). |


#### Example

```bash
curl https://api.lumeapi.site/v1/images/generations \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A minimalist product photo of wireless earbuds on marble",
    "size": "16:9",
    "n": 1
  }'
```

### Model: `seedance-2.0`

- Family: Seedance video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/seedance-2.0

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | seedance-2.0-fast \| seedance-2.0 |
| `prompt` | string | yes | Video description |
| `resolution` | string | no | 480p \| 720p \| 1080p (1080p only on seedance-2.0). Default 720p. |
| `duration` | integer | no | 4–15 seconds. Alias: seconds. |
| `aspect_ratio` | string | no | 16:9 (default) \| 9:16 \| 1:1 \| 3:4 \| 4:3 \| 21:9 \| adaptive |
| `video` | string | array | no | Reference video URL(s) for edit/extend |
| `ref_video_seconds` | number | no | Reference video length for billing; default 2s if omitted |
| `image / images` | string | array | no | First-frame, tail, or multi-ref images |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "A drone shot over misty mountains at sunrise",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'
```

### Model: `seedance-2.0-fast`

- Family: Seedance video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/seedance-2.0-fast

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | seedance-2.0-fast \| seedance-2.0 |
| `prompt` | string | yes | Video description |
| `resolution` | string | no | 480p \| 720p \| 1080p (1080p only on seedance-2.0). Default 720p. |
| `duration` | integer | no | 4–15 seconds. Alias: seconds. |
| `aspect_ratio` | string | no | 16:9 (default) \| 9:16 \| 1:1 \| 3:4 \| 4:3 \| 21:9 \| adaptive |
| `video` | string | array | no | Reference video URL(s) for edit/extend |
| `ref_video_seconds` | number | no | Reference video length for billing; default 2s if omitted |
| `image / images` | string | array | no | First-frame, tail, or multi-ref images |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "A drone shot over misty mountains at sunrise",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'
```

### Model: `veo3.1-fast`

- Family: Veo 3.1 video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/veo3.1-fast

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | veo3.1-fast \| veo3.1-quality \| veo3.1-lite — all fixed 8s output; billed per second × resolution/audio tier |
| `prompt` | string | yes | Video description |
| `resolution` | string | no | 720p \| 1080p \| 4k — or infer from size like 1920x1080 |
| `aspect_ratio` | string | no | 16:9 \| 9:16 (default 16:9) |
| `size` | string | no | Optional pixel size (1280x720 etc.) or aspect ratio string |
| `image_urls / image_url / images` | array|string | no | Reference image(s) for image-to-video (max 3). Not supported on veo3.1-lite. |
| `generation_type` | string | no | frame (first/last frame) \| reference (subject consistency) |
| `generate_audio` | boolean | no | Billing tier only — affects per-second rate. |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Fixed duration` | — | no | All Veo 3.1 tier ids output 8 seconds — do not pass duration or seconds. |
| `veo3.1-lite` | — | no | Text-to-video only. Do not pass image_urls, images, or reference fields. |
| `veo3.1-quality` | — | no | Higher visual fidelity tier at premium per-second rates. Supports T2V and I2V like veo3.1-fast. |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast",
    "prompt": "Cinematic ocean waves at golden hour",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

### Model: `veo3.1-lite`

- Family: Veo 3.1 video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/veo3.1-lite

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | veo3.1-fast \| veo3.1-quality \| veo3.1-lite — all fixed 8s output; billed per second × resolution/audio tier |
| `prompt` | string | yes | Video description |
| `resolution` | string | no | 720p \| 1080p \| 4k — or infer from size like 1920x1080 |
| `aspect_ratio` | string | no | 16:9 \| 9:16 (default 16:9) |
| `size` | string | no | Optional pixel size (1280x720 etc.) or aspect ratio string |
| `image_urls / image_url / images` | array|string | no | Reference image(s) for image-to-video (max 3). Not supported on veo3.1-lite. |
| `generation_type` | string | no | frame (first/last frame) \| reference (subject consistency) |
| `generate_audio` | boolean | no | Billing tier only — affects per-second rate. |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Fixed duration` | — | no | All Veo 3.1 tier ids output 8 seconds — do not pass duration or seconds. |
| `veo3.1-lite` | — | no | Text-to-video only. Do not pass image_urls, images, or reference fields. |
| `veo3.1-quality` | — | no | Higher visual fidelity tier at premium per-second rates. Supports T2V and I2V like veo3.1-fast. |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-lite",
    "prompt": "Cinematic ocean waves at golden hour",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

### Model: `veo3.1-quality`

- Family: Veo 3.1 video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/veo3.1-quality

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | veo3.1-fast \| veo3.1-quality \| veo3.1-lite — all fixed 8s output; billed per second × resolution/audio tier |
| `prompt` | string | yes | Video description |
| `resolution` | string | no | 720p \| 1080p \| 4k — or infer from size like 1920x1080 |
| `aspect_ratio` | string | no | 16:9 \| 9:16 (default 16:9) |
| `size` | string | no | Optional pixel size (1280x720 etc.) or aspect ratio string |
| `image_urls / image_url / images` | array|string | no | Reference image(s) for image-to-video (max 3). Not supported on veo3.1-lite. |
| `generation_type` | string | no | frame (first/last frame) \| reference (subject consistency) |
| `generate_audio` | boolean | no | Billing tier only — affects per-second rate. |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Fixed duration` | — | no | All Veo 3.1 tier ids output 8 seconds — do not pass duration or seconds. |
| `veo3.1-lite` | — | no | Text-to-video only. Do not pass image_urls, images, or reference fields. |
| `veo3.1-quality` | — | no | Higher visual fidelity tier at premium per-second rates. Supports T2V and I2V like veo3.1-fast. |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-quality",
    "prompt": "Cinematic ocean waves at golden hour",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

### Model: `viduq3-pro`

- Family: Vidu Q3 Pro video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/viduq3-pro

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | viduq3-pro — T2V / I2V / first+last frame |
| `prompt` | string | no | Required for text-to-video; optional for image modes |
| `resolution` | string | no | 540p \| 720p \| 1080p — affects billing tier |
| `duration` | integer | no | Output seconds 1–16. Default 5. |
| `aspect_ratio` | string | no | 16:9 \| 9:16 \| 4:3 \| 3:4 \| 1:1 — text-to-video only (omit when image_urls set) |
| `image_urls` | string[] | no | 0=T2V · 1=I2V first frame · 2=first+last frame |
| `audio` | boolean | no | Generate audio (dialogue/SFX). Default true; set false for silent video |
| `seed` | integer | no | Random seed (-1 or omit for random) |
| `image` | string | no | Legacy alias → image_urls (single URL) |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Async flow` | — | no | POST /v1/videos → poll GET /v1/videos/{id} → GET /v1/videos/{id}/content when completed. |
| `Pricing` | — | no | 540p $0.07/s · 720p $0.13/s · 1080p $0.14/s × duration |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-pro",
    "prompt": "A cat walking through neon rain",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio": true
  }'
```

### Model: `wan2.7`

- Family: Wan 2.7 video
- Endpoint: POST /v1/videos (+ poll + content)
- Docs page: /docs/models/wan2.7

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | wan2.7 — unified T2V / I2V / video continuation entry |
| `prompt` | string | no | Required for text-to-video (max 5000 chars). Optional but recommended for I2V. |
| `image_urls` | string[] | no | I2V: 1 image = first frame; 2 images = first + last frame. Mutually exclusive with image_with_roles. Cannot combine with video_urls. |
| `image_with_roles` | array<object> | no | [{url, role: first_frame\|last_frame}] — alternative to image_urls |
| `video_urls` | string[] | no | Video continuation (first URL used). Cannot combine with image_urls/first_frame/audio_url. |
| `resolution` | string | no | 720P \| 1080P (default). Billing: $0.072/s · $0.125/s |
| `duration` | integer | no | 2–15 seconds. Alias: seconds. Default 5. |
| `size` | string | no | T2V only: 16:9 (default) \| 9:16 \| 1:1 \| 4:3 \| 3:4. Alias: aspect_ratio. Ignored when image/video input present. |
| `audio_url` | string | no | Custom audio URL (wav/mp3, 2–30s). T2V = BGM; I2V = motion driver. Cannot combine with video_urls. |
| `negative_prompt` | string | no | Content to avoid (max 500 chars) |
| `prompt_extend` | boolean | no | Smart prompt rewrite (default true) |
| `watermark` | boolean | no | Add "AI生成" watermark (default false) |
| `seed` | integer | no | Random seed (≥0) |
| `image / image_url / images` | string | array | no | Gateway maps to image_urls |


#### Notes

| Field | Type | Required | Description |
|---|---|---|---|
| `Mode routing` | — | no | No image/video → text-to-video. image_urls/image_with_roles → I2V. video_urls → continuation. |
| `Async flow` | — | no | POST /v1/videos → poll GET /v1/videos/{id} → GET /v1/videos/{id}/content when completed. |


#### Example

```bash
curl https://api.lumeapi.site/v1/videos \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7",
    "prompt": "City traffic timelapse at night",
    "resolution": "1080P",
    "duration": 5,
    "size": "16:9"
  }'
```

### Model: `xiaomi/mimo-v2.5`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/xiaomi%2Fmimo-v2.5

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xiaomi/mimo-v2.5",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

### Model: `xiaomi/mimo-v2.5-pro`

- Family: Chat completions
- Endpoint: POST /v1/chat/completions
- Docs page: /docs/models/xiaomi%2Fmimo-v2.5-pro

#### Parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


#### Example

```bash
curl https://api.lumeapi.site/v1/chat/completions \
  -H "Authorization: Bearer $LUMEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xiaomi/mimo-v2.5-pro",
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

## Generic chat parameters (all text models)

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | One of 30 whitelisted model ids (see model tables) |
| `messages` | array | yes | OpenAI-style messages[] — role + content |
| `stream` | boolean | no | SSE streaming |
| `temperature` | number | no | Sampling temperature (model-dependent default if omitted) |
| `max_tokens` | integer | no | Max completion tokens |


## Error codes

- 401 Unauthorized — missing/invalid key
- 402 Insufficient quota — top up wallet
- 403 Model not allowed — use exact catalog model id
- 429 Rate limit — exponential back-off
- 502 Bad gateway — retry

## Contact / product

- Product: LumeAPI portal
- Inference: https://api.lumeapi.site/v1