Skip to main content
Works with Personal and Team keys. Reference photos give Gizmo the exact shape, proportions and look of a real object. You can link public images or upload local files, and label each one with the view it shows.

Upload local files and supply multiple views

Upload local files as multipart/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).
The 201 Created response contains images in upload order. Each item has id, content_type, size_bytes, width, height, and sha256. Save the returned IDs:
Send that JSON to 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. Set reference_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.
Gizmo cannot see surfaces that none of your photos show, so add views of any side that matters.

Python: local files and URL references

For URL-only generation, omit the upload and use 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