create_reference
Create an upload slot for a reference image. Returns an upload URL and a ref_ token: upload the image file with one shell command (curl -T ''), then pass the ref_ token to the reference-image parameter you are filling - every parameter that takes reference images names this tool in its description. This is the ONLY way to supply reference images, and those parameters accept ref_ tokens and nothing else. Image data never goes inside a tool call: a call is JSON, so an embedded image would have to be base64 text that you, the caller, must emit character by character - slow, error-prone, and enough to exhaust your context window. The upload moves the bytes out-of-band instead: a plain HTTP PUT of the raw file, so any HTTP client works; if your environment has no way to send one, install curl. And when the image you want is from one of your OWN recent Logospell generations, skip the upload entirely: pass sourceGeneration and sourceImage and the server copies it directly - the shortcut for extending an existing set in its own style. Accepts PNG, JPEG, or WebP, each at most 500KB, each side between 64px and 768px - resize before uploading if needed; larger reference images do not improve results. A reference is private to your API key and can be used in any number of later calls; it expires 7 days after its last use or re-upload (each use restarts the window), so uploading a few references once can serve a whole session of work. To update a reference, upload a new file to the same upload URL: its image is replaced and its ref_ token stays the same. Costs no credits.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sourceImage | No | Optional, with sourceGeneration: the delivered image filename to use as the reference, exactly as the generation's result, its manifest, or get_generations (the subjects in promptJSON) lists it (e.g. "a_lotus_cradling_a_glowing_pearl.png"). An image larger than the reference limits is downscaled to fit automatically. | |
| sourceGeneration | No | Optional, with sourceImage: fill this reference from one of your own recent generations instead of uploading a file. Pass the generation id - the random segment of its download URL (.../download/<id>/images.zip), also returned by list_recent_generations. The image is copied server-side; nothing is uploaded. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Token to pass to a tool's reference-image parameter. | |
| expiresAt | Yes | When the reference expires if left unused, RFC3339. | |
| uploadURL | Yes | URL to PUT or POST the image file to. |