> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meigen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate Image or Video
> Generate an image or video using an AI model
```
POST /api/generate/v2
```
Submits a generation request. The output is generated asynchronously — use the [status endpoint](#check-generation-status) to poll for completion. The same endpoint serves both image models (GPT Image 2, Nanobanana, Seedream, Midjourney, etc.) and video models (Seedance 2.0, Veo 3.1, Grok Video, etc.) — select via `modelId`.
## Request
### Headers
| Header | Value |
| ------------- | ------------------------------- |
| Authorization | `Bearer meigen_sk_YOUR_API_KEY` |
| Content-Type | `application/json` |
### Body Parameters
The text description of the image to generate.
The model to use for generation. If omitted, the platform default is used (may change over time).
**[List Models](/en/api-reference/endpoint/models) is the authoritative source for valid IDs.** Models are added and retired over time, so resolve IDs at runtime rather than hard-coding a copy of the catalogue. Every model that endpoint returns can be used here, including with an API token.
Frequently used values: `gpt-image-2`, `nanobanana-2`, `midjourney-v8.1` (images); `seedance-2-0`, `veo-3.1` (video).
> `rhart-1.5` (GPT image 1.5) was retired on 2026-04-22 — use `gpt-image-2` instead. `midjourney-v7` was replaced by `midjourney-v8.1` on 2026-05-09 (legacy `midjourney-v7` requests still accepted for backward compatibility).
The aspect ratio for the generated output.
* Default `auto` (recommended): a suitable ratio is picked for you.
* Or pass an explicit value — must be one of the ratios returned in `supported_ratios` from the [List Models](/en/api-reference/endpoint/models) endpoint. Common image ratios: `1:1`, `3:4`, `4:3`, `16:9`, `9:16`, `21:9`, `5:4`, `4:5`.
* Seedance 2.0 also accepts `adaptive`, which matches the dimensions of `referenceImages` or `referenceVideo`. Only use `adaptive` when at least one of those is provided; behavior without a reference is undefined.
* **On Seedance 2.0, an omitted or unrecognised `aspectRatio` resolves to `adaptive`.** Since `adaptive` has nothing to adapt to on a pure text-to-video request, always pass an explicit ratio when you are generating without a reference image or reference video.
The final ratio used is returned both in this endpoint's response and in the status endpoint's `aspectRatio` field.
The output resolution. Availability depends on the model. If omitted, the selected model's default is used.
Available values depend on the model: image models use `1K` / `2K` / `3K` / `4K`; video models use `480p` / `720p` / `1080p` / `4k` (note the lowercase `k` on video). Not every video model offers every value — `4k` is limited to Seedance 2.0's `pro` tier and Veo 3.1, and on Seedance `1080p` also requires the `pro` tier. See [Models](/en/features/models) for each model's supported resolutions and defaults.
GPT Image 2.0 only. Accepts `low` / `medium` / `high`. Other models ignore this parameter.
Array of reference images. Each entry must be either a publicly accessible HTTP(S) URL, or inline base64 data in the form `data:image/png;base64,...`. Local file paths (e.g. `C:/Users/...`) and `file://` URIs are rejected with `400` / `invalid_reference_url`.
Maximum count is per-model — always read `max_reference_images` from [List Models](/en/api-reference/endpoint/models). At the time of writing:
| Limit | Models |
| ----- | --------------------------------------------------------------------------------------- |
| 10 | Seedream 5.0 Pro |
| 5 | GPT Image 2.0, Nanobanana 2, Nanobanana Pro, Seedream 5.0 Lite, Seedream 4.5 |
| 3 | Grok Imagine Quality |
| 2 | Seedance 2.0, Veo 3.1 |
| 1 | Midjourney V8.1, Happyhorse 1.1, Agnes Image 2.1 Flash, Agnes Video 2.0, Grok Video 1.5 |
| 0 | Flux 2 Klein, Z Image Turbo |
Advanced parameters for Midjourney V8.1. Ignored for other models. (Field name preserved for backward compatibility.)
| Field | Type | Default | Range | Notes |
| ------- | ------- | ------- | ----------- | -------------------------------------------- |
| stylize | number | 100 | 0–1000 | |
| chaos | number | 5 | 0–100 | |
| raw | boolean | false | — | |
| iw | number | 1 | 0–2 | |
| sref | string | — | URL or text | |
| sw | number | 100 | 0–1000 | |
| quality | string | `4` | `1` or `4` | Defaults to High (4× compute, no extra cost) |
For Midjourney V8.1 only. How to interpret the reference image.
* `content` — use as subject matter reference
* `style` — extract visual style only
Video duration in seconds. If omitted, the model renders its default length.
| Model | Accepted values | Default |
| --------------- | --------------- | ------- |
| Seedance 2.0 | 4–15 | 4 |
| Veo 3.1 | 4, 6, 8 only | 4 |
| Grok Video 1.5 | 4–15 | 4 |
| Happyhorse 1.1 | 3–15 | 4 |
| Agnes Video 2.0 | 5 only (fixed) | 5 |
**Always pass `duration` explicitly when calling a video model.** The "Default" column is the length that gets rendered when the field is missing — but billing does not follow it. With `duration` omitted, the charge falls back to the model's flat nominal price rather than being computed from the clip length, so it can be noticeably higher than the same request with the duration spelled out. The gap is largest on Veo 3.1, where the fallback is the model's top per-generation price while an explicit `duration: 4` bills at the 4-second rate.
Whatever you send, the amount actually deducted is returned as `creditsUsed` — treat that field as authoritative rather than computing the cost yourself.
Quality tier for models that expose multiple tiers.
* Seedance 2.0: `mini` (default), `fast` or `pro`
* Veo 3.1: `fast` (default) or `pro`
Higher tiers render at higher fidelity for a higher per-second price. If omitted, the model's own default tier is used — note that Seedance 2.0 defaults to `mini`, its cheapest tier. See [Models](/en/features/models) for the full pricing matrix.
For Seedance 2.0 only. Reference video URL for "video continuation" mode. Must be a publicly accessible HTTPS URL (typically a previous generation result URL from the `videoUrl` field).
When this field is present, billing uses the "with reference video" tier (Mini 480p 7, 720p 13; Fast 480p 8, 720p 14; Pro 720p 16, 1080p 28 credits/sec), with the minimum-billable-seconds floor applied (see [Models](/en/features/models)).
For Seedance 2.0 + reference-video continuation only. Duration of the reference video itself (seconds). Used together with `duration` to determine billable seconds (see the pricing table in [Models](/en/features/models)). **Required when `referenceVideo` is set** — if omitted, it is treated as 0, which can lead to unexpectedly low charges and a misconfigured continuation.
## Response
Whether the request was accepted.
The unique ID of the generation request. Use this to poll for status.
Initial status, always `"processing"`.
The number of credits deducted for this generation.
The model used for this generation.
The aspect ratio applied to this generation. Default `auto` picks a suitable ratio, returned here immediately — no need to wait for the first status poll. Useful for reserving a correctly-shaped placeholder in your UI.
Updated credit balances after deduction.
| Field | Type | Description |
| --------- | ------- | ---------------------------------- |
| daily | number | Remaining daily free credits |
| purchased | number | Remaining purchased credits |
| unlimited | boolean | Whether user has unlimited credits |
```json theme={null}
{
"success": true,
"generationId": "550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"creditsUsed": 10,
"modelId": "gpt-image-2",
"aspectRatio": "1:1",
"credits": {
"daily": 2,
"purchased": 50,
"unlimited": false
}
}
```
## Check Generation Status
```
GET /api/generate/v2/status/:generationId
```
Poll this endpoint to check if your image is ready.
### Response (Processing)
```json theme={null}
{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"imageUrl": null,
"imageUrls": null,
"videoUrl": null,
"mediaType": "image",
"error": null,
"aspectRatio": "16:9"
}
```
### Response (Image Completed)
```json theme={null}
{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"imageUrl": "https://images.meigen.ai/generations/xxx.png",
"imageUrls": ["https://images.meigen.ai/generations/xxx.png"],
"videoUrl": null,
"mediaType": "image",
"error": null,
"aspectRatio": "16:9"
}
```
### Response (Video Completed)
```json theme={null}
{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"imageUrl": null,
"imageUrls": null,
"videoUrl": "https://images.meigen.ai/generations/xxx.mp4",
"mediaType": "video",
"error": null,
"aspectRatio": "16:9"
}
```
* **`aspectRatio`** is the final ratio applied to this generation (if you passed `auto`, this is the value that was actually used).
* **`mediaType`** is `image` or `video`. For video generations `imageUrl/imageUrls` are `null`, and vice versa.
* Midjourney V8.1 returns 4 candidate images per generation. `imageUrls` contains all candidates; `imageUrl` always points to the first one. Other image models return a single image.
### Response (Failed)
```json theme={null}
{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"status": "failed",
"creditsStatus": "refunded",
"imageUrl": null,
"imageUrls": null,
"videoUrl": null,
"mediaType": "image",
"error": "Content policy violation",
"aspectRatio": "16:9"
}
```
When a generation fails, credits are automatically refunded. Poll `creditsStatus` to confirm the outcome: `pending` (deducted, not yet settled), `confirmed` (charged), `refunded` (returned to your balance).
## Examples
### Basic generation
Omit `modelId` to use the default (`gpt-image-2`):
```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
-H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A minimalist logo of a mountain, vector style, blue gradient",
"aspectRatio": "1:1"
}'
```
### With reference image
```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
-H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Similar style landscape but with autumn colors",
"modelId": "seedream-5.0-lite",
"aspectRatio": "16:9",
"referenceImages": ["https://example.com/reference.jpg"]
}'
```
### Midjourney V8.1 with style reference
```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
-H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "a warrior princess in an enchanted forest",
"modelId": "midjourney-v8.1",
"aspectRatio": "3:4",
"referenceImages": ["https://example.com/style-ref.jpg"],
"referenceType": "style",
"niji7Options": {
"stylize": 300,
"sw": 500
}
}'
```
### Seedance video (text-to-video)
```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
-H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A majestic eagle soaring over a misty mountain valley at sunrise, cinematic camera movement",
"modelId": "seedance-2-0",
"aspectRatio": "16:9",
"resolution": "720p",
"duration": 5
}'
```
Pricing: no `tier` is passed, so this runs on Seedance's default **Mini** tier — 720p at 16 credits/sec × 5 sec = **80 credits**. Passing `"tier": "fast"` (20 credits/sec → 100 credits) or `"pro"` costs more; see [Models](/en/features/models).
### Seedance video continuation (with reference video)
```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
-H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Continue the scene as the eagle dives toward a river below",
"modelId": "seedance-2-0",
"aspectRatio": "adaptive",
"resolution": "480p",
"duration": 5,
"referenceVideo": "https://images.meigen.ai/generations/eagle-clip.mp4",
"referenceVideoDuration": 3
}'
```
Pricing: no `tier` is passed, so this runs on the default **Mini** tier — 480p with-reference-video rate 7 credits/sec, billable seconds = max(3 + 5, 9) = 9 sec, total **63 credits**. On `fast` the same request costs 8 × 9 = 72 credits. Output video length = `duration` = 5 seconds.
### Auto ratio selection
Omit `aspectRatio` or pass `"auto"` to let MeiGen pick a suitable ratio:
```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
-H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Blog hero banner image, abstract gradient background with code snippets"
}'
```
The actual ratio used is returned as `aspectRatio` — both in the response to this request and on the status endpoint.