# Affogato Developer API

> Programmatic access to every image, video and audio model Affogato serves, billed in the same credits as the user's plan.

- Base URL: https://staging.api.affogato.ai/v1
- OpenAPI: https://staging.api.affogato.ai/v1/openapi.json
- Interactive reference: https://staging.affogato.ai/developers/reference (or https://staging.api.affogato.ai/v1/docs)
- Landing page: https://staging.affogato.ai/developers
- API keys: https://staging.affogato.ai/app/developers (paid plans)
- MCP server: https://staging.api.affogato.ai/mcp (OAuth sign-in, no API key; guide: https://staging.affogato.ai/mcp)

## Authentication

Send `Authorization: Bearer afg_...` on every request. Keys are created on the Developers page of the app and are available on paid plans. Never ship a key in client-side code.

## Credits

Requests spend the credits of the organisation that owns the key, the same credits as the plan.

- `POST /v1/generations/estimate` quotes a request in credits without charging.
- `POST /v1/generations` charges the quoted amount up front and refunds it in full if the generation fails or is cancelled.

## Endpoints

### Models

- `GET /v1/models`: List models. Filters: feature, output_type, q.
- `GET /v1/models/{id}`: One model: parameters, input slots, pricing in credits and an example_request.

### Generations

- `POST /v1/generations/estimate`: Quote a request in credits without charging.
- `POST /v1/generations`: Create a generation: {model, input, webhook_url?, metadata?}. Returns 201 with status "queued". Optional Idempotency-Key header and ?wait=25.
- `GET /v1/generations/{id}`: Read a generation. ?wait=25 long-polls for up to 25 seconds.
- `GET /v1/generations`: List generations, including failed and cancelled ones.
- `POST /v1/generations/{id}/cancel`: Cancel a queued or processing generation.

### Files

- `POST /v1/files`: Upload a file (multipart field "file").
- `POST /v1/files/from-url`: Import a file from a URL: {url}.
- `GET /v1/files`: List your files.
- `DELETE /v1/files/{id}`: Delete a file.

### Prompts

- `POST /v1/prompts/enhance`: Rewrite a prompt for a kind: {prompt, kind: image | video}.

### Webhooks

- `GET /v1/webhooks`: List endpoints.
- `POST /v1/webhooks`: Add an endpoint.
- `PATCH /v1/webhooks/{id}`: Update an endpoint.
- `DELETE /v1/webhooks/{id}`: Remove an endpoint.
- `GET /v1/webhooks/secret`: Read the signing secret.

### Account

- `GET /v1/account`: The organisation, plan and credit balance behind the key.
- `GET /v1/usage`: Credit usage.

## Generation lifecycle

1. Optionally upload inputs with `POST /v1/files` (multipart `file`) or `POST /v1/files/from-url` (`{url}`). Each returns `{id, url, mime_type, ...}`; pass the `id` in a model's input slot.
2. `POST /v1/generations` with `{model, input, webhook_url?, metadata?}`. Returns 201 `{id, status: "queued", ...}`. Send an `Idempotency-Key` header to make retries safe.
3. Follow it: `GET /v1/generations/{id}?wait=25` long-polls up to 25 seconds, or `POST /v1/generations?wait=25` to wait on the create call itself.
4. Statuses: `queued` -> `processing` -> `succeeded` | `failed` | `cancelled`. The last three are terminal.
5. On `succeeded`, `outputs[]` carry `url`, `thumbnail_url`, `mime_type`, `width`, `height`, `duration_ms`.
6. `POST /v1/generations/{id}/cancel` stops a queued or processing generation.

## Webhooks

Pass a per-request `webhook_url`, or register organisation endpoints with `POST /v1/webhooks`.

- Events: `generation.succeeded`, `generation.failed`, `generation.cancelled`.
- Deliveries follow the Standard Webhooks spec, signed with the organisation's `whsec_...` secret (`GET /v1/webhooks/secret`):
  - `webhook-id`: a unique id for this delivery
  - `webhook-timestamp`: Unix seconds the delivery was sent
  - `webhook-signature`: v1,<base64 HMAC-SHA256> over "{id}.{timestamp}.{body}"

## Rate limits

- 120 requests / minute per API key.
- 10 in-flight generations per personal org.
- 25 in-flight generations per team.
- Over a limit the API answers 429 with a `Retry-After` header.

## Errors

Every error is JSON with one shape:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "This generation needs 40 credits; the organisation has 12."
  }
}
```

## Models

`GET /v1/models` lists every model Affogato serves (image, video and audio) unless the operator withholds one. `GET /v1/models/{id}` returns the parameters, input slots, price in credits and an `example_request` you can send as-is.

## MCP server

The same models and tools as a Model Context Protocol server at https://staging.api.affogato.ai/mcp (HTTP transport). Clients sign in with OAuth as a user and choose the workspace whose credits they spend; no API key is involved. Guide: https://staging.affogato.ai/mcp.

Setup:

- Claude.ai: Settings → Connectors → Add custom connector → paste the MCP URL.
- Claude Code: `claude mcp add --transport http affogato https://staging.api.affogato.ai/mcp`
- Cursor: add to .cursor/mcp.json: `{ "mcpServers": { "affogato": { "url": "https://staging.api.affogato.ai/mcp" } } }`
- ChatGPT: Settings → Connectors → Add (developer mode) → paste the MCP URL.
- VS Code: `code --add-mcp '{"name":"affogato","type":"http","url":"https://staging.api.affogato.ai/mcp"}'`

Tools:

- `list_models`: List the models you can call, with filters.
- `get_model`: One model: parameters, input slots, price in credits.
- `estimate_cost`: Quote a request in credits without charging.
- `generate`: Create a generation. Spends credits.
- `get_generation`: Read a generation and its outputs.
- `wait_for_generation`: Block until a generation reaches a terminal status.
- `list_generations`: Recent generations, including failed and cancelled.
- `cancel_generation`: Cancel a queued or processing generation.
- `upload_file`: Upload a file to use as a model input.
- `list_files`: List uploaded files.
- `get_account`: The connected workspace, plan and credit balance.
- `switch_workspace`: Change which of your workspaces the session spends from.
- `enhance_prompt`: Rewrite a prompt the way the studios do.
- `list_voices`: Library voices for text_to_speech.
- `list_headshot_styles`: Curated headshot styles and the control vocabulary.
- `list_talking_head_sets`: Curated background sets for talking heads.
- `list_product_templates`: Scene templates for product ad shots.
- `list_characters`: Your saved characters.
- `lipsync`: Sync a video's mouth to an audio track.
- `text_to_speech`: Speech from text with a library or custom voice.
- `talking_head_keyframe`: Place a person on a set (talking head, step 1).
- `talking_head_video`: Animate a keyframe to a speech track (step 3).
- `headshot`: A professional headshot in a curated style.
- `cast_swap`: Replace the people in a clip with your photos.
- `try_on`: Garments worn by a person or a described model.
- `product_shot`: An ad photo of your product in a scene template.

Spend rails:

- Estimate first: estimate_cost quotes a request in credits and never charges; generate reports the charge in its result.
- Confirmation above a threshold: A generation above the workspace's confirm threshold is not started until the agent confirms it with you.
- Daily cap: Agents stop spending once they reach the daily credit cap set on the Developers page. The cap resets every day.
- Failed and cancelled generations are refunded: Credits are charged up front and returned in full when a generation fails or is cancelled.