Upload local files and supply multiple views
Upload local files asmultipart/form-data; you do not need to host images yourself.
Use the repeated field name files. Let your HTTP client set the multipart boundary
(do not manually set a JSON Content-Type for this request).
201 Created response contains images in upload order. Each item has id,
content_type, size_bytes, width, height, and sha256. Save the returned IDs:
POST /v1/assets. Replace the placeholder IDs with real upload IDs.
Each reference has exactly one of image_id or url. Accepted view labels are
front, back, left, right, top, bottom, perspective, and detail.
Labels are optional hints, not calibrated camera poses. You can supply several
details or perspectives. If you send both reference fields, reference_image_urls
come first, followed by reference_images in order.
Limits: 8 files per upload; 8 references per generation; 20 MiB and 40 million
pixels per file; 80 MiB per upload request. Supported formats are non-animated
PNG, JPEG and WebP. Gizmo keeps your original files unchanged. Uploading the same
file twice returns the same ID. Image IDs are private to the account (Personal or
Team) that uploaded them, so upload and generate with the same key.
GET /v1/images/{id} reads metadata. GET /v1/images/{id}/content downloads the exact
original bytes. Uploaded images stay available while a job waits in the queue.
External URLs must still be reachable when the job starts, so upload the file if
you are not sure the link will last.
Reference fidelity
By default Gizmo reconstructs the object in your photos as closely as it can. It works from your original images; it does not redraw them first. Setreference_intent.mode to change that: reconstruct copies the pictured
object, extract pulls one object out of a busy photo (name it in
reference_intent.target), modify applies the changes in your prompt to the
pictured object, and design treats the photos as inspiration for something new.
The default, auto, chooses from your prompt and references.
Python: local files and URL references
reference_image_urls or
reference_images: [{"url": "https://your-host/your-image.jpg", "view": "front"}].
Replace all example URLs with accessible images. API keys belong on your server, not in browser bundles.
Reference URLs must serve image bytes directly. Redirect responses are not followed; use the final image URL or upload the local file with POST /v1/images.
Upload reference images · Generate one asset · Generate a batch