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 3 Image Klein) and on Seedance 2.5 / 2.0 and HeyGen 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).Asset tokens — write [image1], [video1] or [audio1] inline to tell the model which reference asset a sentence is about: “Match the grade of [image1] and continue the motion of [video1], scored to [audio1]”. Numbering is 1-based and per kind, following the order of referenceImages / referenceVideos / referenceAudios in this request body — [video2] is the second entry of referenceVideos, not the second asset overall. For Seedance, the two kinds are resolved differently before the request reaches the model:

[videoN] / [audioN] are rewritten to the vendor’s own wording — Video 1, Audio 1. A token whose index exceeds the number of clips you actually sent is dropped, so [video3] with two clips attached leaves nothing behind. Writing the vendor wording directly — "Video 1" — works too, and is what MCP and REST callers usually do.
[imageN] and [character:<uuid>] are expanded into a descriptive phrase naming the position of the reference image the token resolves to — [image1] becomes “the subject in reference image 1”, a character token becomes “the character in reference image 2”. The reference planner may merge or reorder images before they reach the model, so the position in the phrase is the one the model actually sees and need not equal N. An [imageN] pointing past the images you sent is left in the prompt as-is rather than dropped — keep image indexes within the images you send.

HeyGen: use the bracket tokens [imageN], [videoN], [audioN] for supplied content references. Out-of-range tokens are rejected before charging; plain Picture N / Video N prose does not create references. First-frame mentions become natural text, not content-image references. Saved-character images share the 9-image budget. First-frame mode cannot mix with content/video/audio.Only the copy sent to the model is rewritten. The prompt stored on the generation keeps your original tokens, so reopening it in the editor still shows the mentions you typed.

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.1, nanobanana-2, midjourney-v8.1 (images); heygen-video-1, seedance-2-5, seedance-2-0, veo-3.1 (video).Nanobanana 2.1 uses modelId: "nanobanana-2.1" and resolution: "2K" (5 credits) or "4K" (8 credits). It is separate from nanobanana-2, which remains available at 5 credits for either resolution.

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 (upgraded in place to V8.2 on 2026-09-02, same ID) (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 referenceVideos 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.

HeyGen uses auto or a supported explicit ratio for text/content/video references. Only its first-frame mode uses adaptive; at 1080p/2K content mode supports 16:9 or 9:16.The final ratio used is returned both in this endpoint’s response and in the status endpoint’s aspectRatio field.

boolean

default:"false"

Opt in to a paid Seedance 2.5 draft, fixed at 480p. Check capabilities.draft.enabled first. Omit for ordinary generation. A completed draft can be rendered as a separately paid 1080p final after reviewing its current quote; see video drafts.

string

The output resolution. HeyGen supports 480p, 768p (default), 1080p, 2k (lowercase k). 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 / 1080p. Seedance 2.0 adds 1080p / 4k on pro; Veo 3.1 also supports 4k. With Seedance 2.0 referenceVideos, the ceiling is 1080p. See Models for the complete matrix.Grok Video 1.5 accepts 480p, 720p, or 1080p on both Lite and Standard, defaulting to 480p. With tier and duration also omitted, it uses Lite × 4 seconds (16 credits at 480p). Keep modelId: "grok-video" for either tier.

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 has been temporarily unavailable since 2026-09-22; the rule below applies whenever it is enabled.) 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 / 2.1, 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.2, Agnes Image 2.5 Flash, Agnes Video 2.5 Flash, Grok Video 1.5 (required — image-to-video only)
0	Flux 3 Image 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[]

HeyGen accepts up to 9 content images (including character images), separate from first-frame mode; these may accompany video or audio, never both. For Seedance: optional structured content references: up to 30 for Seedance 2.5 or 9 for Seedance 2.0. These can coexist with frameReferenceImages, referenceVideos, referenceAudios, and saved-character references. Image, video and audio limits are three independent budgets; saved-character images count toward this image limit.

string

default:"frame"

Controls legacy referenceImages for Seedance 2.5, Seedance 2.0 and HeyGen. HeyGen accepts at most 1 image in frame mode or 9 in content; prefer structured fields for new integrations.

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.2. 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–3	Content image weight
sref	string	—	Numeric codes, `random`, or image URLs	The official ChatGPT plugin requires direct MeiGen-hosted asset URLs
sw	number	100	0–1000
sv	number	6	V8.2 uses `6`	Legacy values are accepted for compatibility, but V8.2 fixes this to 6
weird	number	—	0–3000	Accepted for compatibility; ignored by V8.2
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.2 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 (temporarily unavailable)	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
Grok Video 1.5: lite (default) or standard; both require one first-frame image

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[]

Array of reference videos for models with capabilities.video.referenceVideo.enabled, including Seedance and HeyGen. Every entry must be an https://images.meigen.ai/... URL — either a previous MeiGen generation’s videoUrl, or a file you uploaded through the reference-media upload endpoint. Arbitrary public URLs are not accepted: any other host is rejected with 400 / invalid_reference_video before any credits are deducted. Each URL may appear only once — a duplicate entry is rejected with 400 / invalid_input rather than probed and billed twice.

Model	Clips	Per clip	Total across clips	Size per clip	With-video rates
HeyGen Video 1 (when enabled)	up to 3	1–5s, strict	≤15s	≤16MB	480p 4 / 768p 6 / 1080p 18 / 2K 18 credits/sec
Seedance 2.5	up to 10	2–30s	≤30s	≤200MB	480p 11 / 720p 24 / 1080p 54 credits/sec
Seedance 2.0	up to 3	2–15s	≤15s	≤50MB	Mini 480p 7 / 720p 13, Fast 480p 8 / 720p 14, Pro 720p 16 / 1080p 28 credits/sec (with a reference video, Pro is limited to 720p / 1080p)

The server probes every clip and its detected duration is authoritative — any duration you send is only a diagnostic hint. If probing the reference videos or audio cannot finish in its budget, the request fails with 503 / reference_probe_timeout and retryable: true before any charge: resubmit the same request under the same idempotencyKey. Billing uses the sum of all reference video durations:billable seconds = max(sum of reference video durations + output duration, minimum-billable floor)See Models for the complete rate tables and examples. Seedance reference videos, audio and content images have separate budgets. HeyGen: MP4 aspect ratio must be 1:4–4:1; bill output seconds + each video’s seconds rounded up, with no minimum floor. At most 12 references total; do not combine video with separate audio (reference_video_audio_conflict, rejected before charge). Video-embedded audio is allowed.Legacy alias. The singular referenceVideo (a plain string) is still accepted and is treated as a one-element referenceVideos array; it will keep working indefinitely. If you send both, referenceVideo must be the first element of referenceVideos — any other combination returns 400 / invalid_input.

Editing versus continuation (Seedance 2.5). To continue a clip, describe what happens next. To edit the existing clip (for example, remove lettering or replace a person), use a 4–30 second source and set duration to that source’s rounded whole-second length. If multiple videos could be selected for editing, every source must match the requested duration; using one source avoids ambiguity. The backend may recover an explicit edit-duration rejection once by inheriting the source duration, only when this preserves the already billed output seconds. A mismatch fails and follows normal refund settlement; it never authorizes extra charging. Keep passing a positive integer: duration=-1 and omni_reference_task_type are internal provider parameters, not public API inputs. After a failed/refunded job, correcting the inputs requires a separately authorized new request ID. Retrying an uncertain submission keeps its original ID and exact inputs. For Seedance, a reliably measured reference-video frame rate outside 23.8–60 FPS is rejected before charging with 400 / unsupported_reference_video_frame_rate; re-export at 24–60 FPS. Fragmented or incomplete timing metadata may not provide a reliable frame rate; an upstream rejection can still occur, in which case use the reported terminal status and refund state.

string[]

Array of reference audio clips for models with capabilities.video.referenceAudio.enabled, including Seedance and HeyGen. Every entry must be an https://images.meigen.ai/... URL from the reference-media upload endpoint, in wav or mp3, at most 15MB per clip for Seedance or 16MB for HeyGen. Arbitrary public URLs are not accepted: any other host is rejected with 400 / invalid_reference_audio before any credits are deducted. The format is verified from the file’s own bytes, not from its extension or Content-Type.

Model	Clips	Per clip	Total across clips	Audio-only request
HeyGen Video 1	up to 3	1–15s	≤45s	Not allowed — needs a content image; cannot coexist with reference video
Seedance 2.5	up to 10	2–30s	≤30s	Allowed
Seedance 2.0	up to 3	2–15s	≤15s	Not allowed — needs at least 1 reference image or 1 reference video

Reference audio seconds are not billed. For Seedance, adding audio does not change the price. HeyGen selects the content-reference rate for image/audio input; audio does not add seconds. A Seedance request that carries reference audio but no reference video is billed at the model’s direct (no-video) per-second rate, not the discounted with-video rate.Rejections are pre-charge 400s: reference_audio_not_supported, too_many_reference_audios, reference_audio_total_seconds_exceeded, reference_audio_requires_visual, or invalid_reference_audio for a clip that can’t be read, isn’t wav/mp3, or falls outside the per-clip duration range.

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, and with referenceVideos the billed total is the sum of every probed clip. There is no audio equivalent of this field — audio durations are always probed and never billed.

string

Optional UUID; strongly recommended for composed workflows. Persist it with the exact inputs before submission. MCP calls expose this ordinary-generation handle as requestId.For new API-token requests, the key identifies one logical attempt in the owning account. Reusing it with identical caller inputs recovers that attempt; an existing generation returns deduped: true without another charge. Changed inputs return 409 idempotency_conflict; a different billing context can return request_id_collision. Do not automatically allocate a new key to bypass either conflict. Object-key order is ignored, but other caller values are compared before model defaults. Older jobs may lack the full input fingerprint, so this is not a retroactive guarantee for all legacy receipts. See request-ID recovery.

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.2 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).

Upload Reference Videos and Audio

POST /api/upload/reference-video

referenceVideos and referenceAudios only accept files hosted on images.meigen.ai. Use this endpoint to get a presigned URL for a local file, then upload the bytes yourself. It accepts either an API token (Bearer meigen_sk_...) or a logged-in session access token — Bearer header only, cookies are not read. The same endpoint serves both kinds; pick with kind. An API-token call also requires a positive purchased-credit balance on the owning account. Presigning itself costs nothing, but a zero balance returns 402 — top up the same account and retry. Session calls are not gated this way.

Body Parameters

string

required

The original file name. It must be a non-empty string, but that is the only check: the server neither stores it nor echoes it back, so it never reaches the stored object or the response. The stored object’s extension is derived only from contentType: video/mp4 → mp4, video/quicktime → mov, audio/wav / audio/x-wav / audio/wave / audio/vnd.wave → wav, audio/mpeg / audio/mp3 → mp3. A file named clip.mov but declared as video/mp4 is still stored as .mp4, so send the contentType that matches the file’s real container — vendors read the container from the stored URL’s extension.

string

required

The MIME type of the file, and the only thing that decides the stored extension. Video accepts video/mp4 and video/quicktime; audio accepts audio/wav, audio/x-wav, audio/wave, audio/vnd.wave, audio/mpeg and audio/mp3. It must agree with kind — an audio type sent as kind: "video" (or the reverse) is rejected with 400. Use the exact same value on the follow-up PUT.

number

required

The file’s exact byte length. It is checked against the selected model’s cap before a URL is issued: reference video is ≤200MB on Seedance 2.5 and ≤50MB on Seedance 2.0; reference audio is ≤15MB on both.

string

The model you intend to generate with. It selects which size cap applies. If omitted, a legacy fallback of 15MB is used for audio.

string

default:"video"

video or audio. Defaults to video for backward compatibility with existing integrations.

Response

string

A short-lived URL to PUT the raw file bytes to. Send the same Content-Type you declared above, and no Authorization header.

string

The https://images.meigen.ai/... URL to pass in referenceVideos or referenceAudios once the upload completes.

string

The stored object key, ref-videos/YYYY-MM-DD/{id}.{mp4|mov|wav|mp3}. Audio and video share this prefix.

# 1. Ask for a presigned URL
curl -X POST https://www.meigen.ai/api/upload/reference-video \
  -H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "theme.mp3",
    "contentType": "audio/mpeg",
    "size": 1843200,
    "modelId": "seedance-2-5",
    "kind": "audio"
  }'

# 2. Upload the bytes to the returned presignedUrl
curl -X PUT "<presignedUrl>" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @theme.mp3

# 3. Use the returned publicUrl in referenceAudios

Uploaded reference objects are deleted automatically 7 days after upload. Keep the source file if you need to resubmit later — a generation that already started is unaffected, but a stale publicUrl will fail validation on a new request.

Workflow examples

For N scripts → frames → videos, persistent IDs, in-flight budget reservations and bounded concurrency, see composable workflows. HTTP uses idempotencyKey; MCP uses requestId. New IDs represent new attempts, not timeout recovery.

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.2 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,
    "referenceVideos": ["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.

Seedance 2.5 with two reference videos and one reference audio

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 dive from [video1], then cut to the river camera move of [video2], scored to the rhythm of [audio1]",
    "modelId": "seedance-2-5",
    "aspectRatio": "adaptive",
    "resolution": "480p",
    "duration": 5,
    "referenceVideos": [
      "https://images.meigen.ai/generations/eagle-dive.mp4",
      "https://images.meigen.ai/ref-videos/2026-09-17/river-pan.mp4"
    ],
    "referenceAudios": ["https://images.meigen.ai/ref-videos/2026-09-17/theme.mp3"]
  }'

Pricing: the two clips are probed at 3s and 4s, so the reference sum is 7 seconds. Billable seconds = max(7 + 5, 9) = 12 sec at the 480p with-video rate of 11 credits/sec, total 132 credits. The reference audio adds 0 — it is never billed, and its length does not enter the sum. [video1] / [video2] / [audio1] are rewritten to Video 1 / Video 2 / Audio 1 before the request reaches the model.

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.

Render a completed draft

POST /api/generate/v2/draft-final requires the same authenticated account and meigen:generate permission. For API credentials, pass idempotencyKey (a persistent UUID), sourceDraftGenerationId and confirmedCredits. Check the draft’s authenticated status for the live seedanceDraft.finalCredits quote first. An optional retryFailedGenerationId is only for a separately authorized replacement of that failed final. Recover using /api/generate/v2/requests/{requestId} with meigen:read. A changed price returns 409 price_changed with required; confirm it before using a new ID and changed amount. 410 draft_expired prevents new final renders. Final creation is owner-scoped, reuses the original draft, and charges purchased credits for API calls. Reusing the same ID never automatically replaces a failed job.

Overview

Endpoints

Skills API

Generate Image or Video

Request

Headers

Body Parameters

Response

Check Generation Status

Response (Processing)

Response (Image Completed)

Response (Video Completed)

Response (Failed)

Upload Reference Videos and Audio

Body Parameters

Response

Workflow examples

Examples

Basic generation

GPT Image 2.5 with explicit settings

With reference image

Midjourney V8.2 with style reference

Seedance 2.5 video (text-to-video)

Seedance 2.5 continuation (with reference video)

Seedance 2.5 with two reference videos and one reference audio

Auto ratio selection

Render a completed draft

​Request

​Headers

​Body Parameters

​Response

​Check Generation Status

​Response (Processing)

​Response (Image Completed)

​Response (Video Completed)

​Response (Failed)

​Upload Reference Videos and Audio

​Body Parameters

​Response

​Workflow examples

​Examples

​Basic generation

​GPT Image 2.5 with explicit settings

​With reference image

​Midjourney V8.2 with style reference

​Seedance 2.5 video (text-to-video)

​Seedance 2.5 continuation (with reference video)

​Seedance 2.5 with two reference videos and one reference audio

​Auto ratio selection

​Render a completed draft

Request

Headers

Body Parameters

Response

Check Generation Status

Response (Processing)

Response (Image Completed)

Response (Video Completed)

Response (Failed)

Upload Reference Videos and Audio

Body Parameters

Response

Workflow examples

Examples

Basic generation

GPT Image 2.5 with explicit settings

With reference image

Midjourney V8.2 with style reference

Seedance 2.5 video (text-to-video)

Seedance 2.5 continuation (with reference video)

Seedance 2.5 with two reference videos and one reference audio

Auto ratio selection

Render a completed draft