> ## 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.
# REST API Overview
> MeiGen REST API — integrate AI image & video generation into your app. Supports GPT Image 2, Nanobanana 2, Midjourney, Seedream, Seedance, Veo. Unified endpoints with bearer token auth.
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](/en/mcp/overview) 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](https://www.meigen.ai) under **API Keys**.
```bash theme={null}
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.
```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", "modelId": "gpt-image-2"}'
```
## Response Format
All responses return JSON. Successful responses include a `success: true` field:
```json theme={null}
{
"success": true,
"generationId": "abc-123",
"status": "processing"
}
```
Error responses include an `error` field:
```json theme={null}
{
"error": "Error description"
}
```
## Asynchronous Generation
Image generation is **asynchronous**. The flow is:
1. **Submit** a generation request → `POST /api/generate/v2`
2. **Poll** the status endpoint → `GET /api/generate/v2/status/:id`
3. **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](/en/features/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](/en/features/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.
```json theme={null}
// 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
POST /api/generate/v2
GET /api/models
GET /api/images/:id
Create & revoke in account settings