← Antigravity Manager guide

Images, audio & video

Antigravity Manager: Images, Audio & Video Guide

Use the Images API to generate or edit a picture, the transcription endpoint to turn speech into text, and Chat Completions to ask questions about an image, recording or clip. Start with one small file and a model that can handle the task.

Updated · Instructions for Antigravity Tools v5.0.0. The beta section covers image recovery in v5.0.1-beta.3.

Which endpoint should I use?

Choose the route by the result you want, then select a model available to your account for that task.

Your taskRequest and result in v5.0.0
Understand an imagePOST /v1/chat/completions with image_url → text answer.
Generate an imagePOST /v1/images/generations with a prompt → image data.
Edit with referencesPOST /v1/images/edits with multipart files → image data.
Transcribe speechPOST /v1/audio/transcriptions with a multipart file → JSON containing text.
Ask about audioPOST /v1/chat/completions with input_audio or audio_url → text answer.
Understand a videoPOST /v1/chat/completions with video_url → text answer.

Start API Proxy, check its address and key, and choose the exact model ID from your running instance. The model catalog guide explains how to list IDs and check account access. Audio input arrived in v4.5.9; video input arrived in v4.6.7. Stable v5.0.0 exposes the routes above; speech synthesis and a video-generation endpoint are unavailable in this version.

Run the examples with Python 3

Download multimodal-request.py and place it in a working folder with your test files. It uses Python 3.9 or later and the standard library. Run the commands below from that folder. On Windows, replace python3 with py.

The script asks for your Manager API key with hidden input. It connects to http://127.0.0.1:8045 by default; for another instance, append --base-url "https://YOUR_GATEWAY_HOST" using its actual origin, without /v1. Replace YOUR_VISION_MODEL, YOUR_AUDIO_MODEL or YOUR_VIDEO_MODEL with a suitable ID before running.

Each run sends one request and creates a new media-result-… folder containing the response and extracted output. A successful generation uses account quota. Keep the result folder private if your input contains personal information.

For these examples, the helper accepts PNG/JPEG/WebP images, the audio extensions listed below, and MP4/WebM/MOV video. It caps individual image/video inputs at 20 MiB, audio at 15 MiB and combined edit references at 32 MiB. These are deliberate small-test limits in the helper; the gateway limits are explained separately.

How do I ask a question about an image?

Send the picture in an image_url content block alongside a specific question. Embedding a local file as a data URL avoids remote download and permission problems.

Choose a small chart or screenshot you can inspect yourself. The command below reads chart.png on your computer, embeds its bytes, and saves the model’s answer as answer.txt. Use the Python example setup first.

Image analysis · local file
python3 multimodal-request.py image --model YOUR_VISION_MODEL --file chart.png --prompt "Read the chart title and describe its main trend."

Open the answer and compare the title, labels and trend with the original picture. If the response is generic or mentions a missing image, inspect the forwarded request in Traffic Logs and try a fresh conversation with the same file.

Why does an image URL work in my browser but fail here?

Manager forwards an HTTP(S) image URL to the upstream model service. Use a direct HTTPS file URL that the provider can fetch without your browser’s login, cookies or local network. A page containing an image is a different resource from the image file itself.

For a private chart, keep it local and use the embedded-file example. A localhost, 127.0.0.1 or LAN URL points to a location the provider may be unable to reach. The error Unsupported file URI type is a reason to check the URL scheme and retrieval path first.

If your client sends a file:// reference instead, Manager reads that path on its own host. In Docker, it must exist inside the container. The Python example reads the file on the computer running the script and sends its bytes, which also works with a remote Manager.

How do I generate and save an image?

Send a prompt to /v1/images/generations with an image-generation model, an aspect ratio and a resolution tier. Begin with n: 1 and 1K to check the complete request and download path.

The examples use gemini-3-pro-image; replace it if your account offers another image model. The v5.0.0 route also recognizes the image family gemini-3.1-flash-image. Confirm access in your own instance.

Generate one image · save JSON and image file
python3 multimodal-request.py generate --model gemini-3-pro-image --size 16:9 --image-size 1K --prompt "A small blue house in a snowy field, watercolor illustration."

Open the new result folder and its image-1 file. Check that it opens, shows the requested scene and has a suitable aspect ratio. The script preserves response.json so you can inspect the original result.

Use the same request in your API client

Send this JSON to POST /v1/images/generations with Content-Type: application/json and your Manager key in the Authorization: Bearer … header.

JSON body
{
  "model": "gemini-3-pro-image",
  "prompt": "A small blue house in a snowy field",
  "size": "16:9",
  "image_size": "1K",
  "n": 1,
  "response_format": "url"
}

With response_format: "url", v5.0.0 returns a data URL such as data:image/png;base64,… in data[].url. Decode the bytes after the comma to save the file. The default b64_json format puts bare base64 in data[].b64_json. Choose a client that can display or decode that format.

Which size and quality values should I use?

Use size for the shape and image_size for the resolution tier. For example, size: "16:9" and image_size: "2K" request a landscape image at the 2K tier.

ParameterValues and behavior
size1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 5:4 or 4:5. Pixel strings such as 1920x1080 are interpreted as ratios.
image_size1K, 2K or 4K; takes priority over quality. auto leaves the tier to other settings or the upstream default.
qualitystandard, low or 1k → 1K; medium or 2k → 2K; hd, high or 4k → 4K.
nNumber of generation tasks. More tasks use more account capacity and can take longer. Compare the returned data count with the requested count.

The model chooses output dimensions for the requested ratio and tier. If you need an exact canvas size, inspect the returned image dimensions and resize or crop the saved file afterward. A recognized explicit ratio or tier overrides a model-name suffix; an unsupported ratio falls back to the suffix or 1:1.

For multiple images, some tasks can succeed while others fail. Save the returned images and request only the missing number after checking the error in Traffic Logs. The helper deliberately requests one image per run.

How do I edit with several reference images?

Upload the references to /v1/images/edits as multipart files and explain the role of each image in the prompt.

Image edit · two local references
python3 multimodal-request.py edit --model gemini-3-pro-image --file reference-a.png --file reference-b.png --size 16:9 --image-size 2K --prompt "Use the layout from the first image and the colors from the second."

The helper sends image1 and image2 in the order supplied. For your own client, accepted file fields are image, image[] and numbered names such as image1. Use aspect_ratio to override size, and image_size to override quality. A mask field is accepted as additional image context; check the edited region visually before relying on a precise masked edit.

How do I transcribe an audio file?

Upload one audio file to /v1/audio/transcriptions with an audio-capable model. The response contains a text field; the helper saves it as transcript.txt.

Transcription · one file up to 15 MiB
python3 multimodal-request.py transcribe --model YOUR_AUDIO_MODEL --file meeting.mp3 --prompt "Transcribe the speech in its original language. Keep names as spoken."

The route recognizes .mp3, .wav, .m4a, .ogg, .flac, .aiff and .aif. It detects the format from the filename. Convert an unsupported recording to one of these formats; renaming the extension leaves the original encoding unchanged.

Use the fields file, model and prompt. In v5.0.0, additional Whisper-style options such as response_format, language and timestamp settings are ignored by this handler. Put language or transcription instructions in the prompt, then compare a short passage with the recording.

The file limit is 15 MiB (15 × 1024 × 1024 bytes). Split or compress a larger file before uploading. Duration depends on the encoding and bitrate, so measure bytes rather than assuming a fixed number of minutes. The outer 100 MiB request limit leaves this smaller route limit in place.

Ask questions about the recording

Use Chat Completions with input_audio for a summary, decisions or questions about the content. The helper sends base64 audio with a format and saves the answer as answer.txt.

Audio analysis · text answer
python3 multimodal-request.py audio --model YOUR_AUDIO_MODEL --file meeting.mp3 --prompt "Summarize the decisions and list the action items."

Clients can also send an audio_url block. Remote URLs must be reachable by the provider; embedded input works for private recordings. Check the client setup guide if your client cannot send these content blocks.

How do I analyze a video clip?

Send a short clip in a video_url block to Chat Completions and ask for a text description, sequence of actions or answer about the clip.

Video analysis · local MP4
python3 multimodal-request.py video --model YOUR_VIDEO_MODEL --file clip.mp4 --prompt "Describe the main actions in this clip in order."

The helper embeds the file as data:video/mp4;base64,…; it also accepts WebM and MOV files with their matching MIME types. For your own client, provide video_url.url and, when needed, video_url.mime_type. Manager maps embedded bytes to inlineData and remote HTTP(S) references to fileData.

Choose a short segment whose actions you know, then compare the answer with that segment. If decoding fails, export a fresh MP4 or WebM clip and repeat with the same model. A file extension identifies the container; the model must also handle the actual codec and contents.

The v5.0.0 video helper logs a warning above 20 MiB of inline data. That threshold is advisory in the gateway; the example script uses 20 MiB as its own limit. Keep the entire request within the server and model limits. For a remote clip, use a direct provider-reachable HTTPS file.

What should I check when a media request fails?

Keep the exact error, endpoint, model and Manager version, then repeat with one small file in a fresh session. Change only the file, route or setting involved in the failure.

SymptomNext step
Unsupported file URI typeReplace a local, HTTP-only or authenticated URL with an embedded file or a direct, accessible HTTPS URL.
Unable to process input imageOpen the original file, export it again as PNG/JPEG and test it alone. If several references fail together, try them individually.
Invalid image_sizeUse 1K, 2K, 4K or auto; send ratios through size or aspect_ratio.
400 or 413 with a size errorRead the named limit, reduce the file or combined inputs, and account for base64 expansion.
200 but an empty result or missing imageInspect data, the answer text and any refusal details. Confirm the image model and response format; save any partial results.
429, 503 or no eligible accountFollow account-pool and rate-limit troubleshooting using the response’s error and retry advice.
Timeout or interrupted answerCompare one smaller input at 1K for image generation. Check connection routing and the last completed request stage.

Which size limit applies?

Image references on the Images endpoints are limited to 20 MiB per decoded image and a configurable combined budget, 32 MiB by default. Masks count toward the combined bytes. Audio transcription has its own 15 MiB file limit.

The outer HTTP body limit defaults to 100 MiB. Embedded base64 adds roughly one third to file size, plus JSON overhead; multipart uploads add their own framing. Keep requests comfortably below the smallest applicable limit. Increasing the outer limit cannot remove a route-specific check. See API and configuration reference for server settings.

Why did an earlier screenshot disappear from the conversation?

Check API Proxy → Model Config → Multimodal Settings. When enabled, Multimodal History Freshness Sliding Window replaces older image content with placeholders according to the selected count or memory strategy.

Use Max Fresh Images in Window for the count strategy, or review the memory budget for the memory strategy, then select Save Multimodal Settings. The feature is disabled by default in v5.0.0. Remote image links have a separate stripping option.

If the answer needs an older screenshot, attach it again with your question. A placeholder preserves the conversation’s position but has no original pixels. Save your previous settings and compare the same task after changing the window.

For a persistent failure, use the bug report template with MIME type, byte size, input method and a harmless reproduction file. Keep credentials, private media and signed URLs out of the report.

What changes with image recovery in beta?

In v5.0.1-beta.3, a request rejected with 400 Unable to process input image can retry after its embedded image content is replaced with placeholders. Reattach a corrected image if the next answer still needs its visual details.

For a single-image request, the rejected image’s fingerprint is remembered in a bounded blacklist to intercept repeated submissions. With multiple images, recovery replaces image content in that request without adding every reference to the blacklist. Test each original separately to find the failing input.

This beta also sets image-generation response-header watchdogs to 90 seconds for the primary endpoint and 45 seconds for fallback, within a 135-second overall upstream-call budget. Queueing, later response handling and client timeouts can affect the elapsed time you see.

When upstream returns 200 without image data, beta.3 classifies the response. A policy block or text-only refusal ends the attempt with 400 and includes the reason. Empty candidates or other missing-image responses can be retried and may end with 502. Read the returned detail before retrying. Check your exact build before using this behavior to interpret an error; the stable instructions above target v5.0.0.

Where should I go next?

Use API Proxy setup to check the base URL and key, model routing to check model selection, or return to the Antigravity Manager guide for the full setup sequence.

Version details: image API guide, image request handling, transcription fields and output, video input mapping, and beta.3 image recovery changes.

WINDOWS DOWNLOAD

Archive password

Keep this password to open your Windows download if prompted.