REST API Overview - MeiGen Docs

The MeiGen API lets you generate images and videos programmatically.

Prefer natural language? If you use Claude Code, Cursor, or OpenClaw, try the MCP Server for AI-native image generation without writing HTTP code.

Authentication

API requests require a Bearer token. There are two authentication methods:

API Token (Recommended)

Use an API key that starts with meigen_sk_. Create one from your account settings under API Keys.

Authorization: Bearer meigen_sk_YOUR_API_KEY

API tokens can only use purchased credits. Daily free credits are not available for API calls. Ensure your account has purchased credits before making API requests.

Session Token

For meigen.ai’s own browser integration, a logged-in session access token is accepted. Daily free credits cover basic models only (currently Flux 2 Klein, Agnes Image 2.1 Flash and Agnes Video 2.5 Flash); every other model always requires welcome or purchased credits. Third-party integrations should always use the API Token above.

Base URL

https://www.meigen.ai/api

Before choosing a model, call List Models. The following example requires gpt-image-2.5 to be active. GPT Image 2 remains available under its own ID and pricing when returned by that endpoint.

Request Format

All request bodies must be sent as JSON with the Content-Type: application/json header.

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", "modelId": "gpt-image-2.5", "resolution": "2K", "quality": "low", "modelVariant": "sunburst"}'

Response Format

All responses return JSON. Successful responses include a success: true field:

{
  "success": true,
  "generationId": "abc-123",
  "status": "processing"
}

Error responses include an error field:

{
  "error": "Error description"
}

Asynchronous Generation

Image generation is asynchronous. The flow is:

Submit a generation request → POST /api/generate/v2
Poll the status endpoint → GET /api/generate/v2/status/:id
Read the resulting imageUrl / imageUrls / videoUrl directly from the status response once status === "completed".

Polling Best Practices

Recommended interval: 3 seconds between status checks
Stop when: status is completed or failed
While status is processing, the response includes expectedWaitSeconds (estimated remaining wait for this model and resolution) and pollHintSeconds (how many more seconds to keep polling — 0 means you can stop). Use these instead of a fixed timeout: actual time varies by model, resolution, and duration. Per-model typical times are listed on the Models page.
If your client stops polling early, the job still completes and is still charged — always poll until status reaches a terminal state.

Caching

Some GET endpoints return cached responses:

Endpoint	Cache Duration
`GET /api/models`	1 hour (plus stale-while-revalidate)
`GET /api/images/:id`	1 hour
`POST` endpoints	No caching

Model list changes — a new model, a retired one, a changed default — can therefore take up to an hour to become visible. Plan your own refresh cadence accordingly.

Credits

Each generation deducts credits from your account. Image models charge per image (the amount can vary with resolution and quality); video models are billed per second or per generation, depending on the model. See the Models page for the full per-model pricing table.

Error Responses

Status Code	Meaning
400	Bad request — invalid parameters
401	Unauthorized — invalid or missing token
402	Payment required — insufficient credits
403	Forbidden — model not available on this platform
404	Not found
409	Conflict — idempotency key already used, retry with a new one
5xx	Server error — retry later; credits for a failed generation are automatically refunded

For POST /api/generate/v2, error bodies include extra fields useful for debugging, and most carry a machine-readable code alongside the human-readable error:

`code`	Status	Meaning
`insufficient_credits`	402	Not enough usable credits for this request
`premium_model_paywall`	402	The selected model requires purchased credits (daily free credits don’t apply)
`unsupported_quality`	400	The selected GPT Image model does not support this quality
`unsupported_model_variant`	400	Invalid variant, or `modelVariant` supplied for a model other than GPT Image 2.5
`invalid_model`	400	Model is invalid, inactive, or reserved for a Skill workflow
`unsupported_duration`	400	This model doesn’t support the requested duration
`unsupported_tier`	400	This model doesn’t support the requested tier
`unsupported_resolution`	400	This model/tier doesn’t support the requested resolution
`first_frame_required`	400	This model requires a first-frame image
`reference_video_not_supported`	400	This model/tier/resolution doesn’t support reference-video continuation
`invalid_reference_video`	400	The reference video couldn’t be read or violates the selected model’s limits. Read `capabilities.video.referenceVideo`: Seedance 2.5 accepts 2–30s / ≤200MB; Seedance 2.0 accepts 2–15s / ≤50MB. The URL must be hosted on the platform
`invalid_reference_url`	400	A `referenceImages` entry is not an accepted URL or base64 value
`frame_reference_limit`	400	`referenceMode: "frame"` allows at most 2 images — use `referenceMode: "content"` for more
`too_many_references`	400	Reference image count exceeds this model’s limit
`too_many_characters`	400	At most 3 `[character:...]` references per generation
`character_not_found`	400	The referenced character doesn’t exist or isn’t owned by your account
`characters_not_supported`	400	This model doesn’t support character references
`character_tier_required`	400	This character requires a higher tier
`model_not_available`	403	This model isn’t available on the current platform
`idempotency_conflict`	409	Retry the request with a new `idempotencyKey`

Any other error — including all 5xx responses — means the service is temporarily unavailable. Retry later; the credits for a failed generation are automatically refunded. Errors without a code (such as an unsupported aspect ratio) should be handled by status code and error text.

// 400 — unsupported aspect ratio
{
  "success": false,
  "error": "Aspect ratio 32:9 is not supported by GPT Image 2.0",
  "supportedRatios": ["1:1", "1:3", "16:9", "2:3", "21:9", "3:1", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "9:21"]
}

// 400 — unusable reference image
{
  "success": false,
  "code": "invalid_reference_url",
  "error": "Reference images must be public HTTP(S) URLs or data:image/*;base64 inline data. Local file paths (e.g. C:/Users/...) and file:// URIs are not supported — upload the file to a public URL or pass base64 inline.",
  "received": "C:/Users/me/ref.png"
}

// 402 — premium model, no purchased credits
{
  "success": false,
  "code": "premium_model_paywall",
  "error": "Premium model requires purchased credits",
  "required": 10,
  "available": 4
}

Endpoints

Generate Image

POST /api/generate/v2

List Models

GET /api/models

Get Image

GET /api/images/:id

API Tokens

Create & revoke in account settings

​Authentication

​API Token (Recommended)

​Session Token

​Base URL

​Request Format

​Response Format

​Asynchronous Generation

​Polling Best Practices

​Caching

​Credits

​Error Responses

​Endpoints

Generate Image

List Models

Get Image

API Tokens

Authentication

API Token (Recommended)

Session Token

Base URL

Request Format

Response Format

Asynchronous Generation

Polling Best Practices

Caching

Credits

Error Responses

Endpoints