1. Prepare your account
Create a key in a desktop browser at API Keys. In the same account, open Profile and choose Top Up; mobile purchases use the premium page. Key creation is not available in the mobile interface. All Skill generation spends purchased credits (purchased_credits) only, including the first cutout. There are no API free attempts or daily free credits. The model comparison lists prices; it is not the checkout page.
Keep your key in private local configuration or a secret store. The examples read MEIGEN_API_TOKEN from your local environment; do not paste the secret into a conversation, URL or committed file.
Request bodies are JSON. Each
/run body is limited to 32 KiB, rejects unknown fields and requires a UUID requestId. Upload has its own limits below. Skill IDs are remove-bg, product-detail, brand-poster, white-bg, and upscale.
2. Discover the current contract
endpoint, tool, materials, pricing, maxOutputImages and inputSchema. Use these live values for enums and prices; a missing/null price means unavailable, not free. Successful catalogs may be cached for up to five minutes; errors are not cached. Cross-field rules are also enforced by the server.
HTTP and MCP differ for Product Detail: direct HTTP defaults to three paid modules when modules is omitted. MCP requires an explicit modules field. Send the intended modules explicitly in either integration.
For Upscale, both MCP transports require confirmedCredits on the initial call as well as retries, from the live quote within the accepted user or upstream workflow budget. Direct HTTP keeps it optional.
3. Prepare images
For cutouts, details, posters and backgrounds, all image fields accept only HTTPS URLs onimages.meigen.ai, images.meigen.art or pbs.twimg.com, without credentials or a nonstandard port. Upload other sources first and use the returned imageUrl.
Upscale is different: pass the original public JPEG/PNG/WebP URL directly to /api/skills/upscale/run. Do not shrink it through the ordinary reference-image upload first. For attachment bytes, upload with purpose: "upscale" to preserve dimensions.
success, imageUrl, width, height and firstFrameOnly. Store imageUrl and reuse it for the original request’s recovery.
Temporary source-server 429/5xx responses surface as 503. Retry an upload after waiting; if the failure happened during Upscale submission, recover that submission with its original UUID and parameters.
Uploads decode and re-encode images, remove metadata and preserve alpha where supported. Remote preparation requires a positive purchased-credit balance, checked before reading the body or processing images. Uploading does not create a generation or spend generation credits. For an upload 402, top up the same account and retry the same upload; there is no generation to poll. It is subject to a separate 1,000 upload requests per user per day protection limit. An upload failure has no Skill receipt: fix or retry the upload rather than polling
/skills/status.
Hosts must be able to read actual attachment bytes or access the URL. Never invent a path, URL or base64 value. Upload URLs are not an archival storage promise: save your original and downloaded results.
4. Submit and retain the request
Each workflow page includes a request body. Generate a fresh UUID for a new paid request and save that UUID, the exact JSON body and the resulting job IDs before moving on. The example UUIDs are illustrative; do not reuse them for unrelated work.imageUrl synchronously. Other workflows return generationId or Product Detail items; a successful submission is not proof that rendering has completed.
5. Query and recover
Stop ordinary polling at a terminal result. Show completed images and explain failed/missing modules individually. Refunds must be read from
creditsStatus; neither an HTTP failure nor a missing image alone proves a refund.
After a disconnect or 5xx, check first. Retry only the same requestId and normalized inputs if recovery is allowed. Do not re-upload and silently substitute a new URL. A repeat of a recorded submission returns its existing result without another dispatch. Interrupted workers may hold a lease for about 330 seconds; 409 in_progress returns the remaining retryAfterSeconds for resubmission, while status checks can continue at the normal interval.
A partial batch is recovered as-is; missing modules are not automatically generated again. A replacement batch or a new attempt after failure can charge again and requires intent to retry. A refunded cutout may also create a new paid attempt on retry.
Billing and errors
Product Detail produces 1–6 images and reserves credits per accepted module; other workflows produce one image. Calculate the requested batch total using its current per-image price. Provider failures follow the existing credit ledger and refund rules. There is a 1,000 API requests per user, per Skill, per day protection limit, in addition to any workflow limits. This is not a free allowance and purchasing credits does not remove it. Discovery and status do not spend generation credits; replaying a completed receipt does not consume another dispatch allowance.
MCP adds a
nextAction instruction to these results. Direct HTTP clients implement the same flow using the status/code and fields above; do not expect MCP-only nextAction or resource-link content in the HTTP response.
A known accepted job that is no longer available returns 410 generation_unavailable and its saved job ID. Stop polling; do not automatically resubmit or create a paid replacement. Missing records do not prove a refund. Partial batches retain available results and identify missing records separately.