# Genfire Public API

> REST API for generative media — images, video, speech, music, sound effects, lipsync, upscaling, 3D, trained models (LoRAs), and multi-step workflows (faceless reels, explainers, music videos, picture books, ads). Generation is asynchronous: a submit returns a run, and you poll the run or receive a webhook.

- Base URL: `https://api.genfire.ai/v1`
- OpenAPI 3.1 spec: https://api.genfire.ai/v1/openapi.json
- Full HTML reference: https://api.genfire.ai/v1/docs
- Create an API key: https://www.genfire.ai/dashboard/developers
- CLI, MCP server, SDK and skills: https://www.genfire.ai/developers

## Authentication

Every endpoint below takes a bearer token unless it is marked `no auth`:

```
Authorization: Bearer $GENFIRE_API_KEY
```

Keys are scoped. A call whose key lacks the scope listed on the endpoint fails with `403 insufficient_scope` naming the scope it wanted — read that field rather than widening the key blindly. OAuth access tokens authenticate the same way.

## Conventions that matter

1. **Generation is asynchronous.** A submit returns `202` with a run whose `status` is `queued`. It is NOT a result. Poll `GET /v1/runs/{run_id}` until `status` is `completed` or `failed`, or register a webhook and stop polling. Treating the submit body as output is the single most common integration bug.
2. **Send an `Idempotency-Key` on every generating POST.** Endpoints marked below require it. A retried request carrying the same key returns the ORIGINAL run instead of charging again; the same key with different parameters is rejected rather than silently creating a second run.
3. **Use Genfire model aliases, not raw provider ids.** `GET /v1/models` lists them with capabilities and limits. Aliases stay stable across provider renames and endpoint migrations; a hard-coded provider id breaks when the provider moves.
4. **Price before you spend.** The `estimate-cost` endpoints return a signed `quote_token`. Sending it back on the submit binds the run to the price you were quoted. A `409` means the quote expired or the inputs changed, and the response body carries a fresh quote so you can resubmit in one step.

Errors are RFC 9457 problem documents: a `type`, `title`, `status`, `detail`, and a stable machine-readable `code`. Branch on `code`, never on `detail`.

## Quickstart

```bash
# 1. Submit — returns a queued run, not an image
curl -X POST https://api.genfire.ai/v1/images/generations \
  -H "Authorization: Bearer $GENFIRE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-3","prompt":"a lighthouse in fog","aspect_ratio":"16:9"}'

# 2. Poll until terminal
curl https://api.genfire.ai/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $GENFIRE_API_KEY"
```

## Endpoints

### Authentication

- `POST /oauth/token` — Issue an OAuth access token (no auth)

### CLI Auth

- `POST /cli/auth/sessions` — Start a CLI auth session (no auth)
- `GET /cli/auth/sessions/{sessionId}` — Poll the status of a CLI auth session (no auth)
- `POST /cli/auth/sessions/{sessionId}/exchange` — Exchange an approved CLI auth session for an API key (no auth)

### Account

- `GET /account` — Get the authenticated account (scope: account:read)
- `GET /account/credits` — Get the current credit balance (scope: credits:read)

### Discovery

- `GET /models` — List public model aliases (scope: models:read)
- `GET /models/pricing` — Get per-model base pricing (scope: models:read)
- `POST /models/estimate-cost` — Estimate exact generation cost (scope: models:read)
- `GET /audio/voices` — List voices for speech generation (scope: models:read)

### Usage

- `GET /usage` — Get aggregated API usage (scope: runs:read)

### Uploads

- `POST /uploads` — Create a signed upload URL (scope: uploads:write)

### Influencers

- `GET /influencers` — List your trained influencers (scope: influencers:read)
- `GET /influencers/{influencerId}` — Get a single influencer by id (scope: influencers:read)
- `POST /influencers` — Create an influencer (from photos or from scratch) (Idempotency-Key required; scope: influencers:write)

### Projects

- `GET /projects` — List your projects (scope: projects:read)
- `GET /projects/{projectId}` — Open a project and list what is in it (scope: projects:read)
- `POST /projects` — Create a project or a folder (scope: projects:write)
- `PATCH /projects/{projectId}` — Rename a project, edit its brief, or re-file it (scope: projects:write)
- `DELETE /projects/{projectId}` — Delete a project (scope: projects:write)
- `POST /projects/{projectId}/items` — File assets into a project (scope: projects:write)
- `DELETE /projects/{projectId}/items` — Unfile assets from a project (scope: projects:write)

### Elements

- `GET /elements` — List your reusable image elements (scope: elements:read)
- `GET /elements/{elementId}` — Get a single element by id (scope: elements:read)
- `POST /elements` — Create an element from an image (scope: elements:write)
- `DELETE /elements/{elementId}` — Delete an element (scope: elements:write)

### Brands

- `POST /brands/ingestions` — Create a brand profile from a website URL (scope: brands:write)
- `POST /brands` — Create a brand from supplied fields (scope: brands:write)
- `GET /brands` — List your brands (scope: brands:read)
- `GET /brands/{brandId}` — Get a brand with its products (scope: brands:read)
- `PATCH /brands/{brandId}` — Edit a brand (scope: brands:write)
- `DELETE /brands/{brandId}` — Delete a brand (scope: brands:write)

### Captures

- `POST /captures` — Screenshot a website (Idempotency-Key required; scope: images:write)

### Moodboards

- `GET /moodboards` — List your moodboards (scope: moodboards:read)
- `GET /moodboards/{moodboardId}` — Get a moodboard (scope: moodboards:read)
- `GET /moodboards/presets` — List house-curated preset moodboards (scope: moodboards:read)
- `POST /moodboards/presets/{presetId}/fork` — Fork a preset into your own moodboards (scope: moodboards:read)

### Teams

- `GET /teams` — List your workspaces (scope: teams:read)
- `GET /teams/{teamId}` — Get one workspace (scope: teams:read)

### Video

- `POST /videos/analyses` — Analyse a video scene by scene (Idempotency-Key required; scope: videos:write)

### Generation

- `POST /scenes/blockouts` — Describe a 3D set, get an editable blockout spec (scope: images:write)
- `POST /images/generations` — Generate images (Idempotency-Key required; scope: images:write)
- `POST /videos/generations` — Generate videos (Idempotency-Key required; scope: videos:write)
- `POST /videos/voices` — Create a Kling voice (Idempotency-Key required; scope: videos:write)
- `POST /images/background-remove` — Remove image background (Idempotency-Key required; scope: images:write)
- `POST /videos/upscale` — Upscale a video (Idempotency-Key required; scope: videos:write)
- `POST /images/upscale` — Upscale an image (Idempotency-Key required; scope: images:write)
- `POST /videos/compose` — Cut generated scenes into one finished video (Idempotency-Key required; scope: videos:write)
- `POST /videos/timelines` — Store a re-renderable timeline with exact overlays (scope: videos:write)
- `GET /videos/timelines/{timelineId}` — Read a stored timeline (scope: videos:write)
- `PATCH /videos/timelines/{timelineId}` — Replace a timeline's manifest (scope: videos:write)
- `POST /videos/timelines/{timelineId}/renders` — Render a timeline revision to a video (Idempotency-Key required; scope: videos:write)
- `GET /videos/timelines/{timelineId}/renders` — List a timeline's renders (scope: videos:write)
- `POST /lipsync/generations` — Generate a lip-synced video (Idempotency-Key required; scope: lipsync:write)
- `POST /audio/speech` — Generate speech audio (Idempotency-Key required; scope: audio:write)
- `POST /audio/music` — Generate music (Idempotency-Key required; scope: audio:write)
- `POST /audio/sfx` — Generate sound effects (Idempotency-Key required; scope: audio:write)
- `POST /audio/voice-conversions` — Convert a recording into another voice (Idempotency-Key required; scope: audio:write)
- `POST /audio/transcriptions` — Transcribe audio or video (speech-to-text) (Idempotency-Key required; scope: audio:write)
- `POST /products/extract` — Extract product data from a URL (Idempotency-Key required; scope: products:write)
- `POST /models/3d/generations` — Generate a 3D model from images (Idempotency-Key required; scope: images:write)

### Marketing Studio

- `POST /marketing/products` — Store a product from a URL (scope: marketing:read)
- `GET /marketing/templates` — Browse the ad-template library (scope: marketing:read)
- `GET /marketing/templates/{templateId}` — Get one ad template (scope: marketing:read)
- `GET /marketing/ad-formats` — List the ad formats (scope: marketing:read)
- `GET /marketing/formats` — List the creative formats (genres) (scope: marketing:read)
- `GET /marketing/hooks` — List the opening hooks (scope: marketing:read)
- `GET /marketing/settings` — List the scene settings (scope: marketing:read)
- `GET /marketing/avatars` — List avatars you can put in an ad (scope: marketing:read)
- `GET /marketing/products` — List your stored products (scope: marketing:read)

### Games

- `POST /games/generations` — Generate a browser game (Idempotency-Key required; scope: images:write)
- `POST /games/{gameId}/publish` — Publish or unpublish a game (scope: images:write)
- `POST /games/deployments` — Deploy a game you wrote (Idempotency-Key required; scope: images:write)

### Runs

- `GET /runs` — List recent runs (scope: runs:read)
- `GET /runs/{runId}` — Get a run by id (scope: runs:read)
- `GET /runs/{runId}/output` — Get the output envelope for a run (scope: runs:read)

### Gedi

- `GET /videos/gedi/presets` — Gedi: motion transfer & video edit recipes (scope: models:read)
- `GET /videos/gedi/motion-library` — Gedi: curated motion clips (scope: models:read)

### Trained Models

- `POST /loras` — Train a model on your clips (Idempotency-Key required; scope: videos:write)
- `POST /loras/estimate-cost` — Estimate training cost (scope: models:read)
- `GET /loras` — List trained models (scope: models:read)
- `GET /loras/{loraId}` — Get a trained model (scope: models:read)
- `POST /loras/{loraId}/continue` — Continue training a subject model (Idempotency-Key required; scope: videos:write)
- `DELETE /loras/{loraId}` — Delete a trained model (scope: videos:write)
- `GET /image-styles` — List trained image styles (scope: models:read)
- `POST /style-skills/{skillId}/train` — Train a style skill into an image style (Idempotency-Key required; scope: images:write)

### Workflows

- `GET /workflows` — List executable workflows (scope: workflows:read)
- `GET /workflows/{workflowKey}` — Get one workflow definition (scope: workflows:read)
- `POST /workflows/{workflowKey}/runs` — Execute a workflow (Idempotency-Key required; scope: workflows:write)

### User Workflows

- `GET /user-workflows` — List your editor workflows (scope: workflows:read)
- `POST /user-workflows/{workflowId}/runs` — Run one of your editor workflows (scope: workflows:write)
- `POST /user-workflows/{workflowId}/estimate` — Price a run before starting it (scope: workflows:write)
- `GET /user-workflows/{workflowId}/runs/{runId}` — Get the status and outputs of a workflow run (scope: workflows:read)

### Presets

- `GET /presets` — List runnable presets (scope: workflows:read)
- `GET /presets/{presetId}` — Get one preset (scope: workflows:read)
- `POST /presets/{presetId}/estimate` — Price a preset run and get a quote (scope: workflows:write)
- `POST /presets/{presetId}/runs` — Run a preset (scope: workflows:write)

### Batches

- `GET /batches` — List recent batches (scope: batches:read)
- `GET /batches/{batchId}` — Get a batch by id (scope: batches:read)
- `GET /batches/{batchId}/items` — List items in a batch (scope: batches:read)
- `GET /batches/{batchId}/items/{itemId}` — Get one batch item (scope: batches:read)
- `POST /batches/{batchId}/items/{itemId}/retry` — Retry a failed batch item (scope: batches:write)
- `POST /batches` — Create a batch (Idempotency-Key required; scope: batches:write)

### Webhooks

- `GET /webhooks` — List webhook endpoints (scope: webhooks:read)
- `GET /webhooks/deliveries` — List webhook deliveries (scope: webhooks:read)
- `POST /webhooks` — Create a webhook endpoint (scope: webhooks:write)
- `POST /webhooks/deliveries/{deliveryId}/replay` — Replay a webhook delivery (scope: webhooks:write)
- `PATCH /webhooks/{endpointId}` — Update a webhook endpoint (scope: webhooks:write)
- `DELETE /webhooks/{endpointId}` — Delete a webhook endpoint (scope: webhooks:write)

### Picture Books

- `POST /picture-books/generations` — Generate an illustrated picture book (Idempotency-Key required; scope: images:write)
- `POST /picture-books/estimate-cost` — Estimate picture-book credit cost (scope: account:read)
- `GET /picture-books/{id}` — Read one picture book (scope: account:read)
- `GET /picture-books/styles` — List picture-book art styles (scope: account:read)

### Faceless Reels

- `POST /faceless-reels/generations` — Generate a faceless reel (Idempotency-Key required; scope: reels:write)
- `POST /faceless-reels/estimate-cost` — Estimate reel credit cost (scope: reels:read)
- `GET /faceless-reels/presets` — List niche presets (scope: reels:read)
- `GET /faceless-reels/styles` — List visual styles (scope: reels:read)
- `GET /faceless-reels/music-presets` — List background-music presets (scope: reels:read)
- `GET /faceless-reels/caption-presets` — List caption presets (scope: reels:read)
- `GET /faceless-reels/subscriptions` — List reel subscriptions (scope: reels:read)
- `POST /faceless-reels/subscriptions` — Create a reel subscription (scope: reels:write)
- `PATCH /faceless-reels/subscriptions/{id}` — Update a reel subscription (scope: reels:write)
- `DELETE /faceless-reels/subscriptions/{id}` — Delete a reel subscription (scope: reels:write)
- `POST /faceless-reels/subscriptions/{id}/estimate-episode` — Quote one channel episode (scope: reels:read)
- `GET /faceless-reels/subscriptions/{id}/episodes` — List a channel’s episodes (scope: reels:read)
- `POST /faceless-reels/subscriptions/{id}/episodes` — Produce one channel episode (Idempotency-Key required; scope: reels:write)
- `POST /faceless-reels/subscriptions/{id}/run-now` — Generate a reel now for a subscription (Idempotency-Key required; scope: reels:write)

### Scheduled Tasks

- `GET /tasks` — List scheduled tasks (scope: tasks:read)
- `POST /tasks` — Create a scheduled task (scope: tasks:write)
- `PATCH /tasks/{id}` — Pause, resume or re-route a scheduled task (scope: tasks:write)
- `DELETE /tasks/{id}` — Delete a scheduled task (scope: tasks:write)

### Explainers

- `POST /explainers/generations` — Generate an explainer video (Idempotency-Key required; scope: reels:write)
- `POST /explainers/estimate-cost` — Estimate explainer credit cost (scope: reels:read)
- `GET /explainers/styles` — List explainer visual styles (scope: reels:read)

### Music Videos

- `POST /music-videos/generations` — Generate a music video (Idempotency-Key required; scope: reels:write)
- `POST /music-videos/estimate-cost` — Estimate music-video credit cost (scope: reels:read)
- `GET /music-videos/styles` — List music-video visual styles (scope: reels:read)

### Coloring Books

- `POST /coloring-books/generations` — Draw a coloring book (Idempotency-Key required; scope: images:write)

### Apps

- `POST /apps/deployments` — Deploy an app or website you wrote (Idempotency-Key required; scope: images:write)

### Ads

- `POST /ads/analyze` — Reverse-engineer a competitor ad into a reusable format (scope: workflows:write)

### Media

- `POST /media/frames` — Extract video frames and a contact sheet (scope: videos:write)

## More

- Every request and response schema: https://api.genfire.ai/v1/openapi.json
- Worked examples per endpoint: https://api.genfire.ai/v1/docs
- MCP server (agents, Claude Desktop, ChatGPT): `https://mcp.genfire.ai/mcp`
- CLI: `npm install -g @genfire/cli`