---
title: "Icarus API: the AI-native marketing suite, from your code"
canonical: https://withicarus.com/docs/api
site: Icarus
description: "The Icarus REST API. Make your marketing from your own code: pictures, videos and audio, from the same balance as the app."
---

# Icarus API: the AI-native marketing suite, from your code

The Icarus REST API. Make your marketing from your own code: pictures, videos and audio, from the same balance as the app.

Make your marketing from your own code: pictures, videos and audio with your saved products and characters, paid from the same balance as the app.

- **Get a key:** make one in [Settings, API and MCP](https://withicarus.com/dashboard/settings?tab=api-keys). New to Icarus? Sign up free, then make a key.
- **Address:** `https://myth.withicarus.com/v1`
- **Sign in:** send the key as `Authorization: Bearer <key>`. A key in the address is refused.
- **Limits:** 300 calls a minute per key and 30 paid renders a minute per workspace, shared with MCP. Over the limit you get 429 and `Retry-After`.
- **Retries:** send an `Idempotency-Key` (8 to 128 characters) with every paid call. The same key and request returns the first result for 24 hours and charges once.
- **Renders:** a paid call answers 202 with the shot's `generationId`. Check `GET /v1/generations/{generationId}` every 5 seconds until it is `completed` or `failed`. Files stay at their links.
- **Price first:** add `getCost: true` to any paid call to see its price. Nothing is made.

## Errors

Every error is `application/problem+json` with `status`, `detail` (a sentence you can show), `code` and `requestId`: 400 bad input, 401 no or wrong key, 402 balance too low, 403 the key can't do that, 404 not found, 409 the same request is still running, 422 an `Idempotency-Key` reused for a different request, 429 over the limit.

Make a key: https://withicarus.com/dashboard/settings?tab=api-keys

## Every route

- `GET /v1/me`: Who am I
- `GET /v1/models`: List available models
- `GET /v1/search`: Search the workspace
- `POST /v1/images`: Create an image
- `POST /v1/images/batch`: Create several different images
- `POST /v1/images/edit`: Edit an image
- `POST /v1/images/upscale`: Upscale an image
- `POST /v1/videos`: Create a video
- `POST /v1/videos/batch`: Create several different videos
- `POST /v1/videos/edit`: Edit a video
- `POST /v1/videos/extend`: Extend a video
- `POST /v1/videos/motion`: Copy a clip's movement onto a photo
- `POST /v1/videos/upscale`: Upscale a video
- `POST /v1/audio/speech`: Read a script aloud
- `POST /v1/audio/voice-change`: Change the voice on a recording
- `POST /v1/audio/translate`: Translate a video
- `GET /v1/styles`: List styles
- `POST /v1/styles/{styleId}/apply`: Apply a style
- `GET /v1/generations`: List images, videos and audio
- `GET /v1/generations/{generationId}`: Get an image, video or audio
- `GET /v1/products`: List products
- `POST /v1/products`: Create product
- `GET /v1/products/{productId}`: Get product
- `GET /v1/characters`: List characters
- `POST /v1/characters`: Create character
- `GET /v1/characters/{characterId}`: Get character
- `GET /v1/assets`: List assets
- `POST /v1/assets`: Create asset
- `GET /v1/studios`: List studios
- `GET /v1/folders`: List folders
- `POST /v1/folders`: Create folder
- `POST /v1/folders/{folderId}/items`: Add shots to a folder
- `POST /v1/share-links`: Get a share link
- `GET /v1/voices`: List voices
- `POST /v1/voices`: Make a voice from a recording
- `PATCH /v1/voices/{voice}`: Rename a voice
- `DELETE /v1/voices/{voice}`: Delete a voice
- `POST /v1/uploads`: Get a link to upload a file you have
- `GET /v1/workspaces`: List workspaces
- `POST /v1/workspaces`: Create workspace

The OpenAPI spec lists every route, its fields and what it returns: https://myth.withicarus.com/v1/openapi.json


---

Site: Icarus (https://withicarus.com)
Canonical: https://withicarus.com/docs/api
Contact: tanmay@withicarus.com
