# Givon AI

> AI image, video, music, and voiceover generation through one REST API and MCP. The same call works for every model: only the `input` body changes, and each model exposes its own schema.

Read these docs and help with the task. For a specific model, use its `.md` page (links below) or `GET https://api.givon.ai/api/v1/models/{id}` for the exact schema.

## Agent Instructions

- Use an existing model `id` from the list below. Do not invent model IDs.
- Before generation, read the model schema (its `.md` page or `GET https://api.givon.ai/api/v1/models/{id}`): fields, allowed values, and limits depend on the model.
- Generation is asynchronous: `POST https://api.givon.ai/api/v1/generations` with `{ "type", "model", "input" }` returns `202` with an `id`; poll `GET https://api.givon.ai/api/v1/generations/{id}` until the status is terminal (`succeeded` / `failed` / `canceled`).
- Send a stable `Idempotency-Key` on generation retries. A successful `202` includes `Location` for polling; schema validation returns `422`, and reusing a key with another body returns `409`.
- Authorization: use `Authorization: Bearer gvk_...`, or OAuth authorization code + PKCE. OAuth reads require `givon.read` or `givon.generate`; generation and asset mutations require `givon.generate`.
- Model pages show token pricing. Do not assume a price. A failed generation returns `200` with `status:"failed"` and a stable `errorCode`; it is not an HTTP error, and tokens are not charged for failed generations.

## Models

- [FLUX 3 (flux-3)](https://givon.ai/models/flux-3.md): FLUX 3 is a video generation model from black-forest-labs available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [FLUX Video Upscale (flux-video-upscale)](https://givon.ai/models/flux-video-upscale.md): Black Forest Labs' FLUX 3-powered video upscaler enlarges an existing MP4 by 1.5x to 3x while preserving its aspect ratio. Precise mode stays faithful to the source; creative mode restores and invents fine detail with optional prompt guidance.
- [Gemini Omni 1.1 Flash (gemini-omni-1.1-flash)](https://givon.ai/models/gemini-omni-1.1-flash.md): Gemini Omni 1.1 Flash is a video generation model from google available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [ChatGPT Images 2.0 (gpt-image-2)](https://givon.ai/models/gpt-image-2.md): OpenAI's previous-generation model for complex images: it follows long instructions, multi-object composition, and multilingual in-frame text with high precision. Use it for infographics, slides, packaging, multilingual posters, and full-image edits in 1K, 2K, or 4K.
- [GPT Image 2.5 Flare (gpt-image-2.5-flare)](https://givon.ai/models/gpt-image-2.5-flare.md): GPT Image 2.5 Flare is a image generation model from openai available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [GPT Image 2.5 Sunburst (gpt-image-2.5-sunburst)](https://givon.ai/models/gpt-image-2.5-sunburst.md): GPT Image 2.5 Sunburst is a image generation model from openai available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Grok Imagine (grok-imagine)](https://givon.ai/models/grok-imagine.md): Base xAI image tier: generate and edit full images from text without masks, and compose from several references. Use it for quick concepts and conversational edits when Pro-level precision is not required.
- [Grok Imagine Image 2.0 (grok-imagine-image-2.0)](https://givon.ai/models/grok-imagine-image-2.0.md): The new Grok Imagine image generation release: improved instruction following, in-frame text, and visual consistency for complex scenes. The current public API surface generates from text in five aspect ratios.
- [Grok Imagine Pro (grok-imagine-pro)](https://givon.ai/models/grok-imagine-pro.md): Higher tier of Grok Imagine: more detail, cleaner in-frame text, and stronger composition control from detailed prompts. Use it when the base tier is not sharp enough.
- [Grok Imagine Video (grok-imagine-video)](https://givon.ai/models/grok-imagine-video.md): Fast short-form video with synchronized audio and strong prompt following. It can continue from the last frame, making scene stitching easier. 480p/720p.
- [Grok Imagine Video 1.5 (grok-imagine-video-1.5)](https://givon.ai/models/grok-imagine-video-1.5.md): xAI image-to-video: animates a single source frame with synchronized audio and strong prompt following, with clips up to 15 seconds. Top-3 on the image-to-video arena.
- [HappyHorse 1.0 (happyhorse-1.0)](https://givon.ai/models/happyhorse-1.0.md): Alibaba's top video model: produces a clip with synchronized audio and speech in one pass. Use it for cinematic multi-scene videos with prepared voiceover, from text, a frame, references, or source-video edits. 720p/1080p.
- [HappyHorse 1.1 (happyhorse-1.1)](https://givon.ai/models/happyhorse-1.1.md): HappyHorse 1.1 is a video generation model from alibaba available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [HeyGen Avatar IV (heygen-photo-avatar)](https://givon.ai/models/heygen-photo-avatar.md): Talking avatar from a single photo: the model reads vocal tone and rhythm, then builds lifelike expressions and hand gestures. Sync from text or an existing voiceover.
- [Higgsfield Soul 2.0 (higgsfield-soul-2)](https://givon.ai/models/higgsfield-soul-2.md): Higgsfield Soul 2.0 is a image generation model from higgsfield available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Kling 2.6 (kling-2.6)](https://givon.ai/models/kling-2.6.md): Synchronized audio in a single pass: speech, ambience, and effects are generated directly in-frame without separate dubbing. Use it for budget clips and talking heads when multi-scene control is not needed.
- [Kling 2.6 Motion (kling-2.6-motion)](https://givon.ai/models/kling-2.6-motion.md): Affordable motion-control: transfers movement from a video reference to your character. Use it for simpler motion when 3.0-tier precision is not required.
- [Kling 3.0 (kling-3.0)](https://givon.ai/models/kling-3.0.md): Kling flagship: up to 15 seconds and 4K, stable character identity across scenes, multi-scene direction, and synchronized multilingual audio.
- [Kling 3.0 Motion (kling-3.0-motion)](https://givon.ai/models/kling-3.0-motion.md): Transfers recorded movement, dance, or gestures from a video sample to your full-body character while locking face identity and capturing complex motion. Use it when choreography fidelity and appearance consistency matter.
- [Kling 3.0 Omni (kling-3.0-omni)](https://givon.ai/models/kling-3.0-omni.md): Multi-scene video with synchronized audio: transfers a character's appearance and voice from a video sample into new scenes, though audio must be disabled when that video sample is used. Use it for coherent narratives with one hero.
- [Kling 3.0 Turbo (kling-3.0-turbo)](https://givon.ai/models/kling-3.0-turbo.md): Kling 3.0 Turbo is a video generation model from kling available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Kling Avatar 2.0 (kling-digital-human)](https://givon.ai/models/kling-digital-human.md): Animates a person from a photo and synchronizes speech, natural expressions, and gestures with a voiceover. Useful when you need a speaking or singing presenter from one portrait.
- [Kling Lip-Sync (kling-lip-sync)](https://givon.ai/models/kling-lip-sync.md): Synchronizes lip movement in an existing video with a new audio track. Use it when the video is already shot and you only need dubbing, localization, or speech replacement.
- [Kling O1 (kling-o1)](https://givon.ai/models/kling-o1.md): Combines up to 7 angles of one subject through Elements and keeps its appearance strictly consistent through the entire clip. Use it for character turnarounds, recurring heroes, and product demos.
- [MAI Image 2.5 (mai-image-2.5)](https://givon.ai/models/mai-image-2.5.md): MAI Image 2.5 is a image generation model from microsoft available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [MAI Image 2.5 Pro (mai-image-2.5-pro)](https://givon.ai/models/mai-image-2.5-pro.md): MAI Image 2.5 Pro is a image generation model from microsoft available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [MiniMax H3 (minimax-h3)](https://givon.ai/models/minimax-h3.md): Native 2K video with stereo audio from text, a first and optional last frame, or image and audio references. Use it for expressive motion, legible in-frame text, and multimodal scenes up to 15 seconds.
- [MiniMax H3 Max by fal (minimax-h3-max)](https://givon.ai/models/minimax-h3-max.md): fal's fast post-trained MiniMax H3 variant for stronger prompt adherence and aesthetics. It creates video with synchronized sound from text or a first and optional last frame at 480P/768P for 5–15 seconds.
- [MiniMax H3 Max Turbo by fal (minimax-h3-max-turbo)](https://givon.ai/models/minimax-h3-max-turbo.md): MiniMax H3 Max Turbo by fal is a video generation model from minimax available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Muse Image (muse-image)](https://givon.ai/models/muse-image.md): Muse Image is a image generation model from meta available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Nano Banana (nano-banana)](https://givon.ai/models/nano-banana.md): Entry tier in Google's image family: the most affordable 1K image generation. Dialog editing and reference blending make it useful for volume work and quick drafts.
- [Nano Banana 2 (nano-banana-2)](https://givon.ai/models/nano-banana-2.md): Google's versatile Flash tier: up to 4K, clean text, low latency, and reference consistency. Use it for rapid iteration and high-volume generation when you need strong output below Pro-tier cost.
- [Nano Banana 2 Lite (nano-banana-2-lite)](https://givon.ai/models/nano-banana-2-lite.md): Nano Banana 2 Lite is a image generation model from google available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Nano Banana Pro (nano-banana-pro)](https://givon.ai/models/nano-banana-pro.md): Google's premium tier for complex brand scenes, with strong style-guide adherence, reference handling, lighting, and material rendering. Use it for polished product and portrait visuals, multi-object compositions, and 4K finals.
- [Qwen Image 3.0 (qwen-image-3)](https://givon.ai/models/qwen-image-3.md): Qwen Image 3.0 is a image generation model from alibaba available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Qwen Image 3.0 Pro (qwen-image-3-pro)](https://givon.ai/models/qwen-image-3-pro.md): Qwen Image 3.0 Pro is a image generation model from alibaba available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Recraft V4 (recraft-v4)](https://givon.ai/models/recraft-v4.md): Recraft V4 is a image generation model from recraft available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Recraft V4.1 (recraft-v4.1)](https://givon.ai/models/recraft-v4.1.md): Recraft V4.1 is a image generation model from recraft available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Seedance 2.0 (seedance-2.0)](https://givon.ai/models/seedance-2.0.md): Follows director-style commands such as angle, camera motion, and shot changes through text, with audio generated in one pass. Use it for cinematic reference-guided shots up to 1080p.
- [Seedance 2.0 Fast (seedance-2.0-fast)](https://givon.ai/models/seedance-2.0-fast.md): The same cinematic feel and camera control, but noticeably faster for iterations and volume. Synchronized audio and references, up to 720p.
- [Seedance 2.0 Mini (seedance-2.0-mini)](https://givon.ai/models/seedance-2.0-mini.md): Seedance 2.0 Mini is a video generation model from byteplus available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Seedance 2.5 (seedance-2.5)](https://givon.ai/models/seedance-2.5.md): Flagship Seedance tier for text, image, video-reference, and audio-reference generation at 480p, 720p, or 1080p for 4–30 seconds. Synchronized output audio is enabled by default and can be turned off on compatible routes.
- [Seedream 4.5 (seedream-4.5)](https://givon.ai/models/seedream-4.5.md): Cinematic lighting and stable character identity across generations. Use it for product catalogs, character sheets, and reference-guided edits; a reliable workhorse with 2K/4K output and up to 14 references.
- [Seedream 5.0 Lite (seedream-5)](https://givon.ai/models/seedream-5.md): Lightweight Seedream 5.0 Lite tier: reasons over complex prompts and can search the web, assembling multi-object scenes and topical visuals. Supports example-based reference edits and output up to 3K.
- [Seedream 5.0 Pro (seedream-5-pro)](https://givon.ai/models/seedream-5-pro.md): Seedream for photorealistic commercial hero images, product photography, and edits guided by annotated references. It is strong on natural lighting, skin, and materials while following explicit art direction; 1K/2K output with up to 10 references.
- [SwitchX Image (switchx-image)](https://givon.ai/models/switchx-image.md): Beeble relighting and compositing: transfers an object, background, or light from text, one reference, and an optional mask onto the source photo with physically consistent lighting instead of generating from scratch. 720p and 1080p.
- [SwitchX Video (switchx-video)](https://givon.ai/models/switchx-video.md): Changes the background, object, or lighting in existing footage from text, one reference, and an optional mask while preserving the subject, shape, motion, and expressions. Duration comes from the source video; output is 720p or 1080p.
- [Sync Lipsync v3 (sync-lipsync-v3)](https://givon.ai/models/sync-lipsync-v3.md): Sync Lipsync v3 is a video generation model from sync available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Topaz Astra (topaz-astra)](https://givon.ai/models/topaz-astra.md): Topaz Astra 2 enhances and upscales an existing GenAI video with diffusion-based detail. Upload a source clip, optionally describe the desired restyling, then choose output resolution and enhancement controls.
- [Topaz Starlight Precise 2.5 (topaz-starlight-precise)](https://givon.ai/models/topaz-starlight-precise.md): Topaz Starlight Precise 2.5 improves realism in existing AI-generated or modern archival video, restoring faces, materials, textures, and text up to 4K without creative restyling controls.
- [Veo 3.1 (veo-3.1)](https://givon.ai/models/veo-3.1.md): Google's flagship model for premium cinematic shots: up to 4K video with synchronized audio including dialogue, sound effects, and ambience out of the box. Up to 3 references keep character and style stable.
- [Veo 3.1 Fast (veo-3.1-fast)](https://givon.ai/models/veo-3.1-fast.md): The same sharpness up to 4K and synchronized audio as the flagship, but noticeably faster and cheaper. A workhorse for iterations and most production tasks.
- [Veo 3.1 Lite (veo-3.1-lite)](https://givon.ai/models/veo-3.1-lite.md): The most affordable Veo tier: up to 1080p without 4K and audio that can be turned on or off. Use it for high-volume social content when 4K is unnecessary.
- [Wan 2.7 Image (wan-2.7-image)](https://givon.ai/models/wan-2.7-image.md): Portrait-first image model: control facial features, makeup, and hairstyle through references. Use it for avatars, beauty assets, and consistent character series up to 2K.
- [Wan 2.7 Image Pro (wan-2.7-image-pro)](https://givon.ai/models/wan-2.7-image-pro.md): Wan's 4K tier with prompt reasoning: follows complex multi-step instructions and in-frame text more accurately, including tables and formulas. Use it for demanding deliverables such as posters and packaging.
- [Wan 2.7 Video (wan-2.7-video)](https://givon.ai/models/wan-2.7-video.md): Video generation and editing in one engine: from text, from a photo, with a target final frame, or by editing an existing clip from a description. Up to 1080p.
- [Wan 3.0 (wan-3.0)](https://givon.ai/models/wan-3.0.md): Wan 3.0 is a video generation model from alibaba available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.
- [Wan 3.0 Prime (wan-3.0-prime)](https://givon.ai/models/wan-3.0-prime.md): Wan 3.0 Prime is a video generation model from alibaba available through the Givon AI API. Use the published schema to prepare inputs and request token quotes before generation.

## API

- [OpenAPI 3.1](https://givon.ai/openapi.json) — machine-readable contract for the stable REST envelope.
- Base URL: `https://api.givon.ai/api/v1`

## MCP

- MCP server: `https://api.givon.ai/mcp` (streamable HTTP; API key or OAuth for resource `https://api.givon.ai/mcp`).
- Pass `idempotencyKey` to `givon_generate_content` when retrying. Expected tool failures return `isError:true`; their text contains `{"error":{"code","message"}}` with a stable code.
- `givon_list_models` — List available Givon AI models with their kind, provider, tags, status and token cost. Filter by kind ("image"|"video"), a free-text query, or status. Use givon_get_model_schema to read a model's input fields.
- `givon_get_model_schema` — Get a model's full input JSON Schema, limits, token cost and variants. Read this before calling givon_generate_content so the input fields and allowed values are correct.
- `givon_generate_content` — Launch a Givon AI generation using the same contract as POST /api/v1/generations: { type, model, input }. Call givon_get_model_schema first and pass only fields from that schema.
- `givon_get_generation_status` — Get the status and result URLs of a previously launched generation by its id.
- `givon_get_balance` — Get the current Givon AI token balance for the authenticated account.
- `givon_archive_asset` — Hide an owned Givon owner-media asset from active lists and future reuse. This is a soft archive that keeps audit and existing project links intact.
- `givon_get_asset` — Get one Givon owner media asset by public id or asset:// URI.
- `givon_import_asset` — Import an existing HTTPS URL or data URI into the Givon owner media library and return an asset:// URI. For local files, use `givon asset upload` in the CLI because the remote MCP server cannot read the agent's local filesystem.
- `givon_list_assets` — List reusable Givon owner media assets for the authenticated account. Use this to find asset:// URIs before schema-backed generation.
- `givon_upload_asset` — Upload file bytes into the Givon owner media library and return an asset:// URI. Use this only when the MCP client can provide base64 file content; for HTTPS or data: URIs use givon_import_asset, and for local filesystem paths use the Givon CLI.
- `givon_upload_file_asset` — Upload a native ChatGPT file parameter into the Givon owner media library and return an asset:// URI. ChatGPT passes the file as a top-level `file` object with download_url, file_id, mime_type and file_name.

## Optional

- [Developer documentation](https://givon.ai/help)