Corent Developer Documentation

Integrate AI image and video generation through one orchestration API. Start with the quickstart or explore routing, jobs, agents, and production guidance.

Start the quickstart View API reference

Quickstart

Create a key and make your first request in under a minute.

Image & video API

Every endpoint with request and response examples.

Agent integrations

MCP server, webhooks, streaming, batches, function calling.

Production guidance

Error handling, retries, and what is (never) charged.

Quickstart

Your first image, in one request

Sign up, create an API key from your dashboard, then call the API. The response is synchronous and includes the exact charge.

curl -X POST https://api.corent.tech/v1/images/generate \
  -H "Authorization: Bearer $CORENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a fox reading a book", "preference": "fast"}'

Authentication

Every request needs a bearer token from an API key created in your dashboard. Keep the key server-side only — never in browser code.

Authorization: Bearer co_live_...

Building with AI? (Lovable, Bolt, Cursor, v0)

Give your AI builder the complete machine-readable spec so it integrates Corent correctly on the first try. Paste this into your builder's chat:

Integrate the Corent media generation API into this app.
Read the full spec at https://corent.tech/llms.txt before writing any code.
Base URL: https://api.corent.tech — auth via "Authorization: Bearer <key>".
Images: POST /v1/images/generate (synchronous). Videos: POST /v1/videos/generate
then poll GET /v1/jobs/{id}. Keep the API key server-side only (backend/edge
function), never in browser code.

Machine-readable references: llms.txt (full API spec for LLMs) and openapi.json. Agent webhooks, streaming, batches, and function-calling specs live on the agents docs page.

Preferences and tiers

You send a preference (how to optimize); Corent resolves it to a tier and picks the best underlying implementation inside that tier based on cost, latency, reliability, and current health. Every response tells you which tier served the request — never which model or provider ran underneath.

preference	Image tier	Video tier
fast	corent-image-fast	corent-video-fast
cheap	corent-image-fast	corent-video-fast
balanced	corent-image-balanced	corent-video-premium
quality	corent-image-premium	corent-video-cinematic

Charging behaviour

Corent charges only after a successful result. Images are billed per image when the response returns; videos are billed per second of output when the job completes (the charge appears on GET /v1/jobs/{id}). A request that fails — including a provider failure after internal failover — is never billed. Every successful response carries the exact charge in meta.cost_cents.

Endpoints

POST/v1/images/generate

Generate an image. Corent selects the best implementation for your request. Optional Idempotency-Key header: a repeated key returns the original job instead of generating and charging twice, so timed-out requests are safe to retry blindly.

Request body

{
  "prompt": "a fox reading a book in a cozy library",
  "style": "photorealistic",       // optional
  "preference": "fast",            // fast | cheap | quality | balanced
  "aspect_ratio": "1:1"            // optional
}

Response

{
  "id": "...",
  "status": "completed",
  "images": [{ "url": "https://...", "width": 1024, "height": 1024 }],
  "meta": {
    "model": "corent-image-fast",
    "cost_cents": 2,
    "duration_ms": 1500
  }
}

POST/v1/videos/generate

Start a video generation. Returns 202 immediately with an id — video takes 1-5 minutes and is billed per second of output. Pass image_url to animate an existing image (image-to-video) instead of generating from text alone.

Request body

{
  "prompt": "a small sailboat crossing a calm harbor",
  "preference": "balanced",
  "aspect_ratio": "16:9",
  "duration_s": 5,
  "image_url": "https://... (optional, image-to-video)"
}

Response

{
  "id": "...",
  "status": "processing",
  "meta": { "model": "corent-video-premium" }
}

GET/v1/jobs/{id}

Poll a job's status. Once a video completes, this is where the charge lands. Prefer GET /v1/jobs/{id}/stream (server-sent events) to avoid polling.

Response

{
  "id": "...",
  "status": "completed",
  "videos": [{ "url": "https://..." }],
  "meta": { "model": "corent-video-premium", "cost_cents": 63, "duration_ms": 94000 }
}

POST/v1/images/generate/batch

Up to 50 items in one call (also /v1/videos/generate/batch). Returns 202 with a batch_id and one job id per item; each item bills at the normal rate.

Request body

{
  "items": [ { "prompt": "...", "preference": "fast" }, ... ],  // max 50
  "webhook_url": "https://your-server.com/webhooks/corent",     // optional
  "webhook_secret": "your_shared_secret"                        // optional
}

Response

{ "batch_id": "...", "job_ids": ["...", "..."] }

GET/v1/account/balance

Current prepaid balance, in cents.

Response

{ "balance_cents": 998 }

GET/v1/account/usage

Recent jobs and total spend.

Response

{
  "total_spent_cents": 72,
  "total_jobs": 7,
  "recent_jobs": [ ... ]
}

POST/v1/account/deposit

Creates a Stripe Checkout session to add funds.

Request body

{ "amount_cents": 1000 }

Response

{ "checkout_url": "https://checkout.stripe.com/..." }

GET/v1/requests

Your receipts. Every past request with its exact charge, the tier that served it, how many implementations were considered, and whether failover fired. Failed requests show billed: false and cost_cents: 0. Also GET /v1/requests/{id} for one receipt.

Response

{
  "requests": [{
    "request_id": "...",
    "status": "completed",
    "model": "corent-image-fast",
    "cost_cents": 2,
    "billed": true,
    "candidates_considered": 3,
    "failover_occurred": false,
    "reasoning": "Optimized for cost and speed.",
    "output_url": "https://..."
  }],
  "next_before": null
}

GET/v1/tiers

The machine-readable catalog: every live tier with its purpose, estimated cost, and current status. Public, no authentication — agents can inspect what Corent offers before holding a key.

Response

{
  "tiers": [{
    "name": "corent-image-fast",
    "task_type": "image",
    "description": "Optimized for iteration and drafts, 2-3 second generation",
    "estimated_cost_cents": 2,
    "status": "operational"
  }, ...]
}

PUT/v1/account/api-keys/{id}/limits

Per-key guardrails: requests per minute, concurrent jobs, and a daily cost cap. New keys start at a $10/day cap so a leaked or runaway key is bounded by default. Deliberately requires a dashboard login session, not an API key: a leaked key must never be able to raise its own cap.

Request body

{ "requests_per_minute": 60, "concurrent_jobs": 10, "daily_cost_cap_cents": 5000 }

Response

{
  "requests_per_minute": 60,
  "concurrent_jobs": 10,
  "daily_cost_cap_cents": 5000
}

GET/v1/routing/explain?request_id=...

Which tier served a past request, why, and whether failover occurred.

Response

{
  "model": "corent-image-fast",
  "reasoning": "Optimized for cost and speed.",
  "candidates_considered": 4,
  "failover_occurred": false
}

GET/v1/status

Live operational status for every Corent tier. Public, no authentication needed.

Response

{
  "tiers": [
    { "name": "corent-image-fast", "status": "operational" },
    { "name": "corent-video-cinematic", "status": "operational" }
  ]
}

Errors and retries

Failed requests are never charged — billing happens only after a successful result. Retry guidance below; on a 429, the Retry-After header tells you how many seconds to wait.

Status	Meaning	Charged?	Retry?	What to do
400 / 422	Invalid request	No	No	Fix the highlighted field and resend.
401	Invalid API key	No	No	Check the header: Authorization: Bearer co_live_...
402	Insufficient balance	No	No	Add funds in the dashboard.
404	Resource not found	No	No	Check the job or batch id.
429	Rate limited	No	Yes	Wait the number of seconds in the Retry-After header.
500	Internal error	No	Once	Retry once; if it persists, contact support.
502 / 503	Temporary upstream failure	No	Yes	Safe to retry — routing has already failed over internally.

Duplicate-request safety: send an Idempotency-Key header (any unique string, up to 255 chars) with POST /v1/images/generate or POST /v1/videos/generate. If the same key is seen again, Corent returns the original job instead of generating and charging a second time — a timed-out request can be retried blindly and can never double-bill.

Stuck on an error you can't explain? Email hello@corent.tech with the job id from the response and we can trace exactly what happened.