REST API

The same primitives over HTTP.

Use the API from scripts, CI and backends with a Bearer key. Generation inputs match the corresponding MCP tool, but account checks, uploads and retry identity use the HTTP routes and headers below.

On this page

Base URL and auth
Routes
Example
OpenAPI

Base URL and auth

https://api.agent-media.ai

Authorization: Bearer YOUR_AGENT_MEDIA_API_KEY

Routes

Method	Path	Body	Returns
POST	/v2/generate/{video\|image\|audio}	the tool arguments	201 new job; 200 saved receipt on retry; 202 acknowledgement uncertain. Returns job_id, request_id, credits_deducted, status_url and model details.
POST	/v2/quote/{video\|image\|audio}	the same arguments	200 { credits, usd, model, mode?, quality?, breakdown, auto? }
GET	/v1/videos/{job_id}	–	{ status, video_url, ... }; video_url holds the output for image/audio too. 503 STATUS_UNAVAILABLE: retry the same job.
GET	/v1/me/readiness	–	{ authenticated, credits, generation, uploads, billing_url }; 503 means balance unknown
GET	/v1/models	–	the catalog with modes, prices per quality and recent stats; public
POST	/v1/runs/{job_id}/rate	{ score: 1..5, note? }	200 { job_id, model, score }
GET	/v1/upload-sessions	–	{ sessions }; owned unexpired session IDs and filenames, no image URLs or tokens
GET	/v1/upload-sessions/{session_id}/previews	–	{ previews, unavailable }; owner-only bounded JPEG inspection previews, not generation inputs
POST	/v1/upload-sessions	{}; temporary uploads must be enabled	201 { session_id, upload_url, upload_token, expires_at, max_bytes, max_files, images }
GET	/v1/upload-sessions/{session_id}	–	{ session_id, expires_at, max_bytes, max_files, images }; owner authentication required
POST	/v1/uploads/presign	{ bytes, content_type?, filename? }	{ put_url, upload_key, content_type, bytes, expires_in, ... }; PUT original bytes, then confirm
POST	/v1/uploads/confirm	{ upload_key }	{ image_url, mime, bytes }
POST	/v1/uploads/image	{ image_base64 } or { image_url }	{ image_url }
GET	/v1/characters	–	saved characters with sheet/portrait URLs

The fixed recipes (make_ugc, make_podcast, make_subtitles, selfie, crazy look) remain REST and CLI routes for the dashboard. They are not MCP tools.

Quote before generating

curl -X POST https://api.agent-media.ai/v2/quote/video \
  -H "Authorization: Bearer ma_..." -H "Content-Type: application/json" \
  -d '{ "prompt": "A 28-year-old woman in a bright kitchen, phone framing, holds a serum bottle to the lens and says: \"Okay, I did not expect this to work.\"", "seconds": 5 }'

After reviewing the quote and confirming the budget, submit the same inputs to /v2/generate/video. Send a unique Idempotency-Key header for each intended generation. Keep that key and the exact inputs for retries; changing the key can charge for another run. Poll the returned status_url.

HTTP 201 creates a job; HTTP 200 can replay an existing receipt; HTTP 202 with dispatch_status: unknown means keep polling that job. A temporary HTTP 503 status error is not a failed generation or a confirmed refund.

OpenAPI

Machine-readable spec at https://api.agent-media.ai/openapi.json, interactive reference at https://api.agent-media.ai/docs.