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 Z Image Turbo, Flux 2 Klein, Agnes Image 2.1 Flash and Agnes Video 2.0); 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

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

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
Timeout: allow up to 6 minutes for image models and up to 12 minutes for video. A job that overruns comes back as failed and the credits are refunded in full — the output is discarded, so a late result never arrives. Short of that, the opposite applies: if your client stops polling early, the job still completes and is still charged. Poll until status is terminal (completed / failed), and treat the wall-clock values above only as a backstop. The slowest cases are Seedance 2.0 and Veo 3.1 at high resolution / long duration. Per-model typical times are listed on the Models page.

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
404	Not found
500	Server error

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
`premium_model_paywall`	402	The selected model requires purchased credits
`insufficient_credits`	402	Not enough usable credits for this request
`invalid_reference_url`	400	A `referenceImages` / `referenceVideo` entry is not an accepted URL or base64 value

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