// API REFERENCE

REST API reference.

One call in, media out. Submit a job, then poll or receive a webhook when the asset is ready. Base URL https://api.mcpmediaengine.com.

New here? Start with the Quickstart & MCP guide.

Authentication

Authenticate every request with a bearer token. Create and manage keys from your dashboard. Keep keys server-side — never ship them in client code.

Authorization: Bearer $API_KEY

Endpoints

POST/v1/jobsCreate a media generation job. Returns immediately with a job id.

GET/v1/jobs/{id}Retrieve a job's status and, when complete, its output asset URLs.

GET/v1/jobsList recent jobs for the authenticated account.

GET/v1/modelsList available models and their per-job credit cost.

Create a job

POST /v1/jobs — submit a generation request. Returns instantly with a job id.

Request

curl -X POST https://api.mcpmediaengine.com/v1/jobs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "flux2-turbo",
    "prompt": "editorial hero image, warm light, 16:9",
    "webhook_url": "https://yourapp.com/hooks/media"
  }'

Response

{
  "id": "job_8sK2xq",
  "status": "queued",
  "type": "image",
  "model": "flux2-turbo",
  "created_at": "2026-06-04T18:20:00Z"
}

Body parameters

typestring · requiredMedia type: image or video.

modelstring · requiredModel id (see /v1/models). e.g. flux2-turbo, seedance.

promptstring · requiredText prompt describing the asset to generate.

webhook_urlstringURL called with a POST when the job completes or fails.

nintegerNumber of assets to generate (1–4). Defaults to 1.

metadataobjectArbitrary key/values echoed back on the job object.

Retrieve a job

GET /v1/jobs/{id} — poll until status is succeeded or failed. Statuses: queued → processing → succeeded | failed.

{
  "id": "job_8sK2xq",
  "status": "succeeded",
  "output": [
    { "url": "https://cdn.mcpmediaengine.com/job_8sK2xq/0.png" }
  ],
  "credits_used": 1,
  "completed_at": "2026-06-04T18:20:14Z"
}

Webhooks

Pass webhook_url on a job to skip polling. We POST a JSON body on job.succeeded and job.failed. Respond 2xx within 10s; we retry with backoff.

{
  "event": "job.succeeded",
  "job": {
    "id": "job_8sK2xq",
    "status": "succeeded",
    "output": [{ "url": "https://cdn.mcpmediaengine.com/job_8sK2xq/0.png" }]
  }
}

Models

Fetch live pricing from GET /v1/models. Current models:

flux2-turboimageFast, low-cost default.

seedreamimageHigh-fidelity photographic output.

nano-bananaimageBalanced quality / cost.

gpt-image-2imageStrong prompt adherence + text rendering.

nano-banana-proimageHighest-detail image tier.

seedancevideoTeaser-length video. Pro plan and above.

Errors

Errors return a JSON body with a code and human-readable message.

400invalid_requestMissing or malformed parameter.

401unauthorizedMissing or invalid API key.

402insufficient_creditsAccount is out of credits.

404not_foundNo job with that id for this account.

429rate_limitedToo many requests — back off and retry.

5xxserver_errorTransient error. Retry with exponential backoff.

Rate limits scale with your plan. On 429, back off exponentially and retry.

Ready to ship? Grab a key and make your first call.

Get an API key Quickstart