One request for every model
Every generation is a POST /api/v1/generations with the body { type, model, input }, where type is image, video, music or voiceover. GET /api/v1/models lists models with prices, and GET /api/v1/models/{id} returns the input JSON schema: allowed fields, limits and the cost of variants. The generation runs in the background: the response returns an id, which you use to get the status and the result.
The price is known before the run. POST /api/v1/generations/quote takes the same body and charges nothing. The maxTokens field sets a ceiling: if the price has risen above it, the generation does not start and no tokens are charged. The Idempotency-Key header keeps a repeated submission from creating a second generation.
IDEMPOTENCY_KEY="${IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.givon.ai/api/v1/generations \
-H "Authorization: Bearer $GIVON_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"image","model":"chatgpt-images-2","input":{"prompt":"a cat in glasses reading a book"}}'Your own files, voices, avatars and the account
Voices and avatars are read-only: a voice id goes into a voiceover, and avatar views go in as image or video references.
| Path | What it does |
|---|---|
| POST /api/v1/assets | Uploads your own file and returns an asset:// URI for the model's reference fields. |
| POST /api/v1/assets/import | Imports from an HTTPS link or a data URI and returns an asset:// URI. |
| GET /api/v1/voices | Lists the account's trained voices together with the base voices. |
| GET /api/v1/avatars | Lists Studio avatars with their ready views. |
Instructions, keys and model reference are collected in your account under Integrations: the Agent, Chat, CLI, Skills and API tabs, a playground and cURL, JavaScript and Python examples for each model, Keys and request History. The unlimited images of the Studio Pro plan do not apply in the API and MCP: images are paid in tokens, while the plan's percentage discounts on video models remain.
llms.txt, llms-full.txt and openapi.json on givon.ai are open without sign-in, and model pages are copied for an agent through the For AI menu.
MCP and CLI without a key
The MCP server https://api.givon.ai/mcp gives an AI agent the same actions: find a model, read its schema, get a price, start a generation, check its status, upload a file, list voices and avatars, check the balance. No key is needed to connect: on the first request a browser opens, you sign in to Givon and click Allow and connect. In claude.ai, Claude Desktop and ChatGPT, Givon is added as a connector at the same URL.
The command curl -fsSL https://givon.ai/install.sh | sh installs the givon CLI, brings its own Python if needed, opens the browser sign-in and installs the Givon skills for Codex and Claude Code. The skills are grouped into Generation, Prompts, Editing and sound, Marketplaces, Copy and marketing, and Stories; before each run the agent tells you the price in tokens and waits for your confirmation.
Where it gets used
Content in your own product
A service, CRM or catalog calls POST /api/v1/generations and gets the result by the generation id.
A task for an AI agent in the terminal
Codex or Claude Code with the Givon skills makes marketplace cards, a video with voiceover and music, or a series of shots with one character.
Generation from a web chat
In claude.ai or ChatGPT with the Givon connector, a video, cover or voiceover starts from an ordinary conversation.
A series with one voice and avatar
A script passes the same voice id from GET /api/v1/voices and the avatar views from its assets into every generation in the series.
FAQ
Do I need an API key to connect an AI agent?
No. Claude Code, Cursor and web chats sign in to Givon through the browser on the first request; if Codex did not open the browser, givon login signs you in. A key is needed for direct REST requests, CI and servers without a browser; you create it in your account under Integrations → Keys.
How much does a generation through the API cost?
As many tokens as quote returns for the same request body; they are charged to the account's shared balance. The Studio Pro unlimited images do not apply in the API and MCP, while the plan's percentage discounts on video models remain.
How is MCP different from the CLI?
The givon CLI with skills is the main path for agents in the terminal: the skills pick a model, write the prompt and edit the video. MCP connects the same actions to the claude.ai and ChatGPT web chats and, optionally, to terminal agents.
Can I create a voice or an avatar through the API?
No. The API reads the account's existing voices and Studio avatars and passes them into a generation; voice cloning and avatar creation are not available through the API.
What if I lose the key secret?
The secret is shown once at creation and cannot be recovered. You can reissue or revoke the key under Integrations → Keys.
