Generate Image or Video

POST /api/generate/v2

Submits a generation request. The output is generated asynchronously — use the status endpoint to poll for completion. The same endpoint serves both image models (GPT Image 2.5, GPT Image 2, Nanobanana, Seedream, Midjourney, etc.) and video models (Seedance 2.5, 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

string

required

Long prompts for GPT Image 2 and 2.5 are automatically shortened to fit model limits. Keep essential instructions and preservation constraints explicit.The text description of the image or video to generate. To reference a saved character, include [character:<uuid>] inline — e.g. "[character:550e8400-e29b-41d4-a716-446655440000] standing in a neon-lit alley, cinematic lighting". Up to 3 character references per generation.Supported on image models that accept reference images (all except Flux 2 Klein) and on Seedance 2.5 / 2.0 for video. Character images consume the same content-reference image budget as user-uploaded images. An unsupported model, a nonexistent or inaccessible character, or too many references returns 400 (characters_not_supported, character_not_found, too_many_characters); some characters require a higher tier (character_tier_required).

string

The model to use for generation. If omitted, the platform default is used (may change over time).List 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.5, gpt-image-2, nanobanana-2, midjourney-v8.1 (images); seedance-2-5, 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).

string

default:"auto"

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 endpoint. Common image ratios: 1:1, 3:4, 4:3, 16:9, 9:16, 21:9, 5:4, 4:5.
Seedance 2.5 and 2.0 also accept adaptive, which follows the input media. Use it for first/last-frame and referenceVideo requests.
For Seedance 2.5 text-to-video or referenceMode: content, pass an explicit supported ratio when you need a specific frame shape.
On Seedance 2.0, an omitted or unrecognised aspectRatio resolves to adaptive. Pure text-to-video has nothing to adapt to, so always pass an explicit ratio when 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.

string

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). Seedance 2.5 supports 480p / 720p only. Seedance 2.0 adds 1080p / 4k on pro; Veo 3.1 also supports 4k. With Seedance 2.0 referenceVideo, the ceiling is 1080p. See Models for the complete matrix.

string

Quality is model-specific. GPT Image 2.5 accepts low (Standard), medium (Medium), high (High), xhigh (Extra High), and max (Max). GPT Image 2 accepts only low / medium / high. For GPT Image models, omit the field or use auto to follow the model’s configured default (currently low).Grok Imagine Image 2.0 accepts low (Standard, default) / medium. Read extra_config.qualities and extra_config.pricing from List Models. Unsupported GPT quality values return 400 / unsupported_quality.

string

GPT Image 2.5 only: sunburst (quality priority, configured default) or flare (speed priority). Both support generation and reference-image editing, with the same price for the same resolution and quality. References do not change this setting automatically.Use modelId: "gpt-image-2.5" with this field. Do not use the variant names as separate model IDs or pass modelVariant with GPT Image 2 or another model. Invalid combinations return 400 / unsupported_model_variant.

string[]

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.

Agnes Video 2.5 Flash — image-to-video ignores aspectRatio. This model derives the output ratio from the first frame itself. For images hosted on images.meigen.ai (anything you generated or uploaded on MeiGen) we crop the frame to your requested aspectRatio at the CDN edge first, so the output matches what you asked for. For any other source — an external URL or data: base64 — the image is passed through as-is and the output ratio follows your image, not aspectRatio.If the exact output ratio matters for an external image, pre-crop it to that ratio before sending, or pass the imageUrl of an earlier generation (already on our CDN).

Maximum count is per-model. For image models and video first/last-frame input, read max_reference_images from List Models. Seedance content mode instead uses extra_config.maxContentReferenceImages. At the time of writing:

Limit	Models
16	GPT Image 2.5, GPT Image 2.0
14	Nanobanana 2, Nanobanana Pro
10	Seedream 5.0 Pro, Seedream 4.5
3	Grok Imagine Image 2.0
2	Seedance 2.5, Seedance 2.0, Veo 3.1 — default `frame` mode (first/last frame), see `referenceMode` below
1	Midjourney V8.1, Agnes Image 2.1 Flash, Agnes Video 2.5 Flash, Grok Video 1.5 (required — image-to-video only)
0	Flux 2 Klein

In content mode, Seedance 2.5 accepts up to 30 images and Seedance 2.0 accepts up to 9. When character tokens are present, their resolved images count toward the same limit.

string[]

Optional structured Seedance input for the first and last frame, in that order. Maximum 2. Use this together with contentReferenceImages when you need frame control and content guidance in the same request. Structured fields take precedence over the legacy referenceImages / referenceMode pair.

string[]

Optional structured Seedance content references: up to 30 for Seedance 2.5 or 9 for Seedance 2.0. These can coexist with frameReferenceImages, referenceVideo, and saved-character references. Image and video limits are counted separately; saved-character images count toward this image limit.

string

default:"frame"

Seedance 2.5 and Seedance 2.0 only. Controls how those providers interpret referenceImages.

frame (default) — first/last-frame reference, up to 2 images.
content — content reference, not tied to a frame position. Read the current API limit from extra_config.maxContentReferenceImages (30 for Seedance 2.5 and 9 for Seedance 2.0).

Do not send this field for Veo, Grok, or Agnes video models; their providers do not implement content-reference mode and keep their normal frame behavior. Exceeding a supported limit returns 400 — frame_reference_limit in Seedance frame mode or too_many_references for content/other per-model limits.

object

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
profile	string	—	Alphanumeric code	Midjourney personalization profile; works alongside `sref`
quality	string	`4`	`1` or `4`	Defaults to High (4× compute, no extra cost)

string

default:"content"

For Midjourney V8.1 only. How to interpret the reference image.

content — use as subject matter reference
style — extract visual style only

number

Video duration in seconds. If omitted, the model renders and bills at its own default length:

Model	Accepted values	Default
Seedance 2.5	4–30	4
Seedance 2.0	4–15	4
Veo 3.1	4, 6, 8 only	4
Grok Video 1.5	4–15	4
Agnes Video 2.5 Flash	5 only (fixed)	5

The amount actually deducted is always returned as creditsUsed — treat that field as authoritative rather than computing the cost yourself.

string

Quality tier for models that expose multiple tiers.

Seedance 2.0: mini (default), fast or pro
Veo 3.1: fast (default) or pro

Seedance 2.5 has no tier; omit this field. Higher tiers render at higher fidelity for a higher price. If omitted, the model’s own default tier is used — Seedance 2.0 defaults to mini. See Models for the full pricing matrix.

string

Reference video URL for Seedance 2.5 or Seedance 2.0 continuation. It must be a publicly accessible HTTPS URL (typically a previous generation result’s videoUrl).

Model	Reference input	Output	With-video rates
Seedance 2.5	2–30s, ≤200MB	4–30s; 480p / 720p	11 / 24 credits/sec
Seedance 2.0	2–15s, ≤50MB	4–15s; tier-specific, up to 1080p	Mini 7/13, Fast 8/14, Pro 16/28 credits/sec

For both models, billable seconds = max(reference duration + output duration, minimum-billable floor). See Models for the complete rate tables and examples. The system detects the reference video’s actual duration automatically. A reference video can be submitted together with content-reference images; their limits are independent.

number

Deprecated compatibility hint; omit it in new integrations. If supplied, it must be a finite non-negative number and may be compared with the detected value for diagnostics, but it does not control billing or clipping. The server-probed duration is authoritative for Seedance 2.5 / 2.0 continuation.

string

Optional UUID. Guards against duplicate submissions — e.g. retrying after a timeout on a flaky connection.Resubmitting the same key for the same account returns the original generation instead of creating a new one, and does not deduct credits again; the response includes deduped: true. In rare cases you may get 409 / idempotency_conflict — generate a new key and retry.

Response

boolean

Whether the request was accepted.

string

The unique ID of the generation request. Use this to poll for status.

string

Initial status, always "processing".

number

The number of credits deducted for this generation.

string

The model used for this generation.

string

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.

This is the ratio requested for the generation. It matches the delivered media in every case except one: Agnes Video 2.5 Flash image-to-video with a first frame we can’t pre-crop (an external URL or data: base64) — there the output follows your first frame’s own ratio instead. If exact framing matters for that case, read the dimensions from the returned video rather than trusting this field.

boolean

Present and true when this response is for a resubmission that matched an earlier request’s idempotencyKey — no additional credits were deducted.

object

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

{
  "success": true,
  "generationId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "creditsUsed": 6,
  "modelId": "gpt-image-2.5",
  "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)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "imageUrl": null,
  "imageUrls": null,
  "videoUrl": null,
  "mediaType": "image",
  "error": null,
  "aspectRatio": "16:9",
  "expectedWaitSeconds": 25,
  "pollHintSeconds": 20
}

expectedWaitSeconds — estimated total wait for this model and resolution, from submission.
pollHintSeconds — how much longer to keep polling; counts down toward 0, at which point you can stop. Use it to drive your polling loop instead of a fixed timeout — reference-video continuation and higher tiers can take longer than a plain text-to-video request.
Both fields are only present while status is "processing".

Response (Image Completed)

{
  "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)

{
  "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)

{
  "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 current image default. Read is_default from List Models; the default can change:

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"
  }'

GPT Image 2.5 with explicit settings

Use this example when gpt-image-2.5 appears in the active model list.

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 studio product photo of a ceramic coffee mug, soft window light",
    "modelId": "gpt-image-2.5",
    "aspectRatio": "4:5",
    "resolution": "2K",
    "quality": "low",
    "modelVariant": "sunburst"
  }'

This 2K Standard request costs 6 credits. For 4K Max with speed priority, set resolution: "4K", quality: "max", and modelVariant: "flare" (88 credits). Add referenceImages to edit or use visual references without an extra reference-image charge. The authoritative charge is creditsUsed. Reuse the same idempotencyKey only when retrying the same request. A changed quality or variant is a new request and needs a new key.

With reference image

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-4.5",
    "aspectRatio": "16:9",
    "referenceImages": ["https://example.com/reference.jpg"]
  }'

Midjourney V8.1 with style reference

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 2.5 video (text-to-video)

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-5",
    "aspectRatio": "16:9",
    "resolution": "720p",
    "duration": 5
  }'

Pricing: Seedance 2.5 has no tier. 720p costs 39 credits/sec × 5 sec = 195 credits.

Seedance 2.5 continuation (with reference video)

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-5",
    "aspectRatio": "adaptive",
    "resolution": "480p",
    "duration": 5,
    "referenceVideo": "https://images.meigen.ai/generations/eagle-clip.mp4"
  }'

Pricing: 480p with-reference-video rate is 11 credits/sec. Assuming the uploaded reference is 2 seconds long (detected automatically), billable seconds = max(2 + 5, 9) = 9 sec, total 99 credits. Output length remains duration = 5 seconds.

Auto ratio selection

Omit aspectRatio or pass "auto" to let MeiGen pick a suitable ratio:

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.

Overview

Endpoints

Generate Image or Video

Request

Headers

Body Parameters

Response

Check Generation Status

Response (Processing)

Response (Image Completed)

Response (Video Completed)

Response (Failed)

Examples

Basic generation

GPT Image 2.5 with explicit settings

With reference image

Midjourney V8.1 with style reference

Seedance 2.5 video (text-to-video)

Seedance 2.5 continuation (with reference video)

Auto ratio selection

​Request

​Headers

​Body Parameters

​Response

​Check Generation Status

​Response (Processing)

​Response (Image Completed)

​Response (Video Completed)

​Response (Failed)

​Examples

​Basic generation

​GPT Image 2.5 with explicit settings

​With reference image

​Midjourney V8.1 with style reference

​Seedance 2.5 video (text-to-video)

​Seedance 2.5 continuation (with reference video)

​Auto ratio selection

Request

Headers

Body Parameters

Response

Check Generation Status

Response (Processing)

Response (Image Completed)

Response (Video Completed)

Response (Failed)

Examples

Basic generation

GPT Image 2.5 with explicit settings

With reference image

Midjourney V8.1 with style reference

Seedance 2.5 video (text-to-video)

Seedance 2.5 continuation (with reference video)

Auto ratio selection