# Corent API

> Corent is a media generation API: one key, one endpoint family, automatic model routing.
> Describe what you want; Corent reads the prompt, routes it to the best model at this moment,
> and reroutes automatically if a provider fails. You never pick or manage models.

Base URL: https://api.corent.tech
Auth: HTTP header `Authorization: Bearer co_live_...` (create keys in the dashboard at https://corent.tech/dashboard/api-keys)
Billing: prepaid credits. Images are billed per image; video is billed per second of output. Every response includes the exact charge. Failed generations are never charged.
OpenAPI spec: https://api.corent.tech/openapi.json

IMPORTANT for app builders: keep the API key SERVER-SIDE only (backend function / edge function).
Never ship it in browser code. There is no CORS allowance for arbitrary origins by design.

## MCP server (for AI agents / assistants)

Corent ships an MCP server so an agent can generate media directly.
  Hosted (no install): https://mcp.corent.tech/mcp   (Streamable HTTP; pass your key per your client's remote-MCP config)
  Claude Code:  claude mcp add corent -e CORENT_API_KEY=co_live_... -- npx -y corent-mcp
  Config file:  {"mcpServers":{"corent":{"command":"npx","args":["-y","corent-mcp"],"env":{"CORENT_API_KEY":"co_live_..."}}}}
Tools: plan, create (describe-what-you-want; Corent decides image/video/tier),
generate_image, generate_video, get_job, get_balance, get_status.
All tools return structured content; read-only tools (plan, get_job, get_balance, get_status)
are annotated readOnlyHint so clients can skip confirmation prompts on them.
The `create` tool takes a max_cost_cents spend ceiling so an autonomous agent can't overspend.

## Generate an image (synchronous, 2-20s)

POST https://api.corent.tech/v1/images/generate
Content-Type: application/json
Idempotency-Key: <any unique string, optional>   // a repeated key returns the ORIGINAL job instead
                                                 // of generating/charging twice; retries are safe

{
  "prompt": "a minimalist workspace, natural light",   // required
  "preference": "balanced",   // optional: fast | cheap | quality | balanced (default balanced)
  "style": "photorealistic",  // optional: photorealistic | artistic | anime | logo | text_focused
  "aspect_ratio": "1:1"       // optional: 1:1 | 16:9 | 9:16 | 4:3 | 3:4 | 3:2 | 2:3 (default 1:1)
}

Response 200:
{
  "id": "<job uuid>",
  "status": "completed",
  "images": [{ "url": "https://...", "width": 1024, "height": 1024 }],
  "meta": { "model": "corent-image-balanced", "cost_cents": 5, "duration_ms": 12659 }
}

## Generate a video (asynchronous — poll the job)

POST https://api.corent.tech/v1/videos/generate
{
  "prompt": "aerial drone shot over a pine forest at sunrise",  // required
  "preference": "balanced",   // optional: fast | cheap | quality | balanced
  "aspect_ratio": "16:9",     // optional: 16:9 | 9:16 | 1:1
  "duration_s": 5,            // optional seconds; video is billed per second
  "image_url": "https://..."  // optional: animates this image (image-to-video) instead of text-to-video
}

Response 202: { "id": "<job uuid>", "status": "processing", "meta": { "model": "corent-video-premium" } }

Then poll every few seconds:
GET https://api.corent.tech/v1/jobs/{id}
-> { "id": "...", "status": "processing" | "completed" | "failed",
     "videos": [{ "url": "https://..." }],           // when completed
     "meta": { "model": "...", "cost_cents": 31, "duration_ms": 109890 } }
Typical completion: 1-5 minutes depending on tier.

## Plain-language requests (Corent plans everything)

POST https://api.corent.tech/v1/intent
{ "intent": "a vertical 10 second clip for TikTok of a sunrise over the alps" }
-> returns the plan Corent would execute (task type, tier, aspect ratio, duration, cleaned prompt)
   plus estimated_cost_cents, WITHOUT generating.

POST https://api.corent.tech/v1/intent/execute
{ "intent": "...same as above...",
  "confirm_estimated_cost_cents_up_to": 50 }   // required spend ceiling in cents; if the estimate
                                               // exceeds it, nothing generates and executed=false
Returns { "plan": {...}, "executed": true, "actual_cost_cents": ..., "result": {...} } where result
contains the image URL (synchronous) or a video job id to poll via /v1/jobs/{id}.

## Batches (up to 50 items per call)

POST https://api.corent.tech/v1/images/generate/batch   (also /v1/videos/generate/batch)
{ "items": [ { ...same fields as the single endpoint... } ],   // max 50 items
  "webhook_url": "https://...",                                 // optional: each item POSTs its result when done
  "webhook_secret": "..." }                                     // optional: HMAC-SHA256 signature in X-Corent-Signature
Response 202: { "batch_id": "...", "job_ids": ["...", ...] }
GET https://api.corent.tech/v1/batches/{batch_id} -> { "total": 50, "completed": 12, "failed": 0, ... }
Each item bills at the normal per-generation rate; there is no batch discount.

## Streaming job progress (instead of polling)

GET https://api.corent.tech/v1/jobs/{id}/stream   (server-sent events)
Pushes an event on every state change (processing with progress_percent where available,
completed, failed) and closes at a terminal state. Also: add "webhook_url" (+ optional
"webhook_secret") to any generate request to get a 202 immediately and the full result
POSTed to your URL when done.

## Receipts and discovery

GET https://api.corent.tech/v1/requests          -> your receipts: per-request exact charge, tier,
     candidates considered, failover_occurred, billed true/false. Failed requests: cost_cents 0.
GET https://api.corent.tech/v1/requests/{id}     -> one receipt.
GET https://api.corent.tech/v1/tiers             -> PUBLIC machine-readable catalog: every live tier
     with purpose, estimated_cost_cents, and live status. No auth needed; inspect before holding a key.

## Account

GET https://api.corent.tech/v1/account/balance   -> { "balance_cents": 995 }
GET https://api.corent.tech/v1/account/usage     -> recent jobs with charges
POST https://api.corent.tech/v1/account/deposit  -> { "checkout_url": ... } (Stripe; amount_cents in body)
POST https://api.corent.tech/v1/account/deposit/crypto -> { "checkout_url": ... } (crypto via NOWPayments; min 1000 cents)

## Tiers (Corent picks the model inside each tier)

corent-image-fast      $0.02/image        drafts and iteration, ~1-4s
corent-image-balanced  $0.05/image        general purpose, ~5-15s
corent-image-premium   from $0.06/image   production quality, logos, photorealism
corent-video-fast      ~$0.044/second     quick drafts
corent-video-premium   ~$0.062/second     high quality
corent-video-cinematic ~$0.161/second     premium cinematic with audio

Your `preference` field maps to a tier:
  images: fast->corent-image-fast, cheap->corent-image-fast,     balanced->corent-image-balanced, quality->corent-image-premium
  videos: fast->corent-video-fast,  cheap->corent-video-fast,    balanced->corent-video-premium,  quality->corent-video-cinematic
Live per-tier estimates: GET /v1/tiers (authoritative; the table above is indicative).

## Errors

401 { "detail": "Invalid API key" }          -> key missing/typo'd/revoked; check Authorization header format: Bearer co_live_...
402 { "detail": "Insufficient balance" }     -> add credits in the dashboard
429 { "detail": { "error": "rate_limited", ... } } -> respect Retry-After header
502/503                                       -> transient provider issue; safe to retry once

## Rate limits

Default 60 requests/minute per key, 120/minute per account, 10 concurrent jobs.
New keys start with a $10/day (1000 cent) cost cap so a leaked or runaway key is bounded by default.
Per-key daily cost caps configurable via the dashboard or PUT /v1/account/api-keys/{id}/limits.
Batches count as one request per item against rate and spend limits (video batches also hold a concurrency slot per item; image batches do not).