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 (to grow an existing set, use its extend tool instead: extend_image_set, extend_character_set or extend_illustration_set). 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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "create_reference"
}
}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 or get_generations (the subjects, variations or scenes 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. |