API

Three on-ramps. One credit wallet.

Ounie accounts hit the REST endpoints with a bearer key. AI assistants — including the Ounie AI Team — connect over MCP and get a native tool surface. One-off scripts can skip the account entirely and pay per image in USDC via x402. All three drive the same generation engine, and account calls draw your shared Ounie credits (1 credit = 1¢) — refused when short, never overdrawn.

Overview

Text-to-image and text-to-video across 13 frontier models, as an API.

A generation is the unit of work: one prompt, one model, one output. Images are waited on in-request (usually 10–60 seconds) and return finished URLs; videos return immediately as running and you poll until they settle (one to fifteen minutes). Outputs are stored on permanent public URLs.

Prompts can optionally be grounded in up to 3 of your Ounie brains — facts from your own knowledge base folded into the prompt before the model sees it. Grounding is free and needs an ounie.com credential (session cookie or the master key); it's excluded on x402 because a keyless caller has no Ounie account.

Base URL https://generative.ounie.com · JSON everywhere · prompts up to 2,000 characters · max 5 generations in flight per account.

Authentication

Three credentials, one rule: the caller owns everything it touches.

Session cookie

The dashboard's own auth. Every REST endpoint accepts it — the docs below work from your browser session too, and cookie calls can ground in your brains.

App key · gnv_live_…

Minted at Dashboard → API keys (shown once, up to 5 active). Send it as Authorization: Bearer gnv_live_… or, where headers can't be set, as ?api_key=gnv_live_…. It generates and bills normally but has no ounie.com credential, so it cannot ground in brains.

Master key · ounie_live_…

One key across the whole Ounie app fleet. Enable "Use across Ounie apps" on the key at ounie.com → Settings → API keys and it works here as a Bearer too — and because it IS an ounie.com credential, it unlocks brain grounding for agents.

Credits & refusal semantics

Reserve → settle → refund. Refused, never overdrawn.

Submitting a generation reserves the model's full credit price from the caller's shared Ounie wallet. Delivery settles the reservation; a failed, timed-out, or aborted job refunds it automatically and in full — exactly once, however many pollers race.

If the wallet can't cover the reserve, the call is refused up front with 402 insufficient_credits and a buy_credits_url (https://ounie.com/dashboard/settings). Nothing is charged, nothing goes negative — an agent on your key can never overdraw you.

Free by design: GET reads, the gallery, downloads, share pages, reference-image uploads, and brain retrieval.

REST endpoints

The same routes the dashboard uses. All accept cookie or Bearer auth.

POST/api/generations— Create a generation

{
  "model_id": "flux-dev",          // from GET /api/pricing
  "prompt": "golden hour over a glass city, 35mm",
  "aspect_ratio": "16:9",          // optional, model's options
  "duration": 5,                   // video only
  "resolution": "720p",            // wan family only
  "reference_image_key": "…",      // optional, from /api/media/reference
  "brain_ids": ["…"],              // optional grounding (≤ 3)
  "ground": true
}

Reserves the model's price (FLUX Dev = 12 credits, up to Veo 3.1 = 900). Images wait in-request and usually return 200 with finished URLs; video returns 202 with status "running" — poll the detail route.

GET/api/generations— List generations

GET/api/generations/:id— Poll one generation

Lazily advances a still-rendering job — each call can settle or refund it. This is how agents wait on video. Free.

DELETE/api/generations/:id— Abort or delete

A queued/running job is aborted with a full refund; a finished one is deleted along with its stored outputs. Free.

POST/api/generations/:id/share— Toggle the share page

{ "public": true }

Succeeded generations only. Returns share_url (/g/:id). Default is private — media goes public only by explicit owner action. Free.

POST/api/media/reference— Upload a reference image

Multipart "file" or JSON {"url": "https://…"} — up to 10 MB, sniffed server-side, stored private. Returns a reference_image_key for image-to-image models (Nano Banana 1/2). Free.

GET/api/brains— List your brains

For the grounding picker. Cookie or master-key callers get their ounie.com brains; a gnv_live_ key gets an honest empty list. Free.

GET/api/credits— Credit balance

Spendable credits + monthly included remaining + buy_credits url. Free.

GET/api/pricing— The price list

Public — the full model catalog with live per-model (and per-duration) credit prices. No auth.

MCP server

Native tools for Claude, Cursor, ChatGPT, the AI SDK — and the Ounie AI Team.

Endpoint  https://generative.ounie.com/api/mcp   (legacy SSE: /api/sse)
Header    Authorization: Bearer gnv_live_…       (or ounie_live_…)

# Clients that can't set headers append the key to the URL —
# this is how the Ounie AI Team connects:
https://generative.ounie.com/api/mcp?api_key=gnv_live_…

Tool	What it does	Cost
generate_image	One image from a text prompt; waits for the render and returns a permanent public URL. Optional brain grounding (master key).	2–20 credits by model
generate_video	Start one video render; returns immediately with a generation_id to poll.	150+ credits (reserved)
get_generation	Poll a generation; advances a still-rendering job and settles or refunds when it finishes.	free
list_generations	List your generations, filterable by modality and status.	free
list_models	The model catalog with live credit prices. No auth required.	public
list_brains	Your Ounie brains for grounding (master ounie_live_ key only).	free
get_credit_balance	Spendable Ounie credits in the shared wallet.	free
get_pricing	Credit tiers + the x402 endpoint. No auth required.	public
whoami	The authenticated key's owner and key id.	free

Brain grounding over MCP needs the master ounie_live_ key — it's forwarded upstream to read your brains. A gnv_live_ app key generates normally but ungrounds silently (and list_brains tells it why).

x402 · keyless pay-per-call

No account, no key, no credits — the USDC is the payment. Images only.

# 1 — ask; the server answers with payment terms
curl -X POST https://generative.ounie.com/api/x402/image \
  -H "Content-Type: application/json" \
  -d '{"prompt":"isometric server room, blueprint style","model_id":"flux-dev"}'
# → 402 { "x402Version": 1, "accepts": [{ "maxAmountRequired", "payTo", "asset", … }] }

# 2 — sign the terms with your wallet and retry
curl -X POST https://generative.ounie.com/api/x402/image \
  -H "Content-Type: application/json" \
  -H "X-Payment: <signed payload>" \
  -d '{"prompt":"isometric server room, blueprint style","model_id":"flux-dev"}'
# → 200 { "ok": true, "url": "https://…/outputs/….png",
#          "payment": { "tx_hash", "payer", "paid_atomic_usdc" } }

Endpoint	Models	Price
POST /api/x402/image	fast/standard image tiers — FLUX Schnell/Dev, Nano Banana, Seedream 5.0	150000 atomic USDC (≈ $0.15)

Plainly: x402 is image-only, and brain-grounded actions are excluded — an x402 caller has no Ounie account and no brains to ground in. Video needs an account because a multi-minute render outlives an x402 response; the reserve → settle → poll lifecycle exists for exactly that.

Errors

Errors are JSON: { "error": "code", … }. A charged-then-failed job always refunds.

Code	Status	Meaning
unauthorized	401	Missing or invalid credential — send a session cookie, a gnv_live_ Bearer, or ?api_key=.
insufficient_credits	402	The wallet can't cover the reserve. The body includes required, balance, and buy_credits_url. Nothing was charged.
invalid_payload / prompt_too_short / prompt_too_long	400	The request body failed validation (prompt is 3–2,000 chars; aspect_ratio/duration/resolution must be one of the model's options).
unknown_model / wrong_modality	400	model_id isn't in the catalog, or an image model was sent to a video call (and vice versa).
prompt_blocked	400	The prompt failed content screening. Not charged.
model_rejects_reference	400	A reference image was sent to a model that doesn't accept one.
too_many_running	429	You already have 5 generations in flight — wait for one to finish or abort one.
not_found	404	No generation with that id belongs to this account.
generation_unavailable	503	Generation isn't configured on this deployment.
generation_failed	502	The provider refused or failed the job. Reserved credits were refunded.

The generation object

Returned by every generation route as { "generation": … }.

{
  "id": "9f2c…",                    // uuid
  "modality": "image",              // image | video
  "model_id": "seedream-5.0",
  "tier": "image_premium",
  "status": "succeeded",            // queued | running | succeeded | failed | aborted
  "prompt": "golden hour over a glass city, 35mm",
  "prompt_enhanced": "…",           // the grounded prompt, when grounding ran
  "params": { "aspect_ratio": "16:9" },
  "grounded": true,
  "grounding_thin": false,          // true = brains had nothing relevant
  "brain_ids": ["…"],
  "has_reference": false,
  "outputs": ["https://…/outputs/….png"],
  "is_public": false,               // share page off by default
  "error": null,
  "source": "api",                  // web | api | mcp
  "credits_reserved": 20,
  "credits_spent": 20,              // 0 on failure — the reserve was refunded
  "created_at": "2026-07-13T…",
  "completed_at": "2026-07-13T…"
}