Home
Logospell · Docs

Reference tools

Hand Logospell an image by token, uploaded or taken from one of your own generations. create_reference, list_references and delete_references are free.

scroll ↓
01 / 04 · How it works
One short handshake

create_reference

create_reference supplies your images to any Logospell tool that accepts reference images, in a short handshake your AI can perform by itself.

the full flow
# Step 1 - your AI calls the tool
create_reference()

# Step 2 - the tool responds with an upload URL and a reference token
uploadURL: "https://mcp.logospell.com/refs/ref_abc123"
ref: "ref_abc123"

# Step 3 - your AI uploads your image file to the upload URL
curl -T my-style-ref.png "https://mcp.logospell.com/refs/ref_abc123"

# Step 4 - your AI passes the token to calls to Logospell tools that accept image references
generate_image_set(
  style: "stained-glass leadlight rendering",
  styleReferences: ["ref_abc123"],
  subjects: ["phoenix", "mermaid", "dragon"]
)

Already have a Logospell generation? Your AI can skip the upload and fill the reference straight from one of its images, the shortcut for a new set in an earlier set's look:

from your own generation
# Your AI fills the reference from an image it already generated - no upload
create_reference(
  sourceGeneration: "a268ab1a725cc8a9ab43bd34",
  sourceImage: "a_lotus_cradling_a_glowing_pearl.png"
)

# Same response as the flow above, with the image already in place
sourceGenerationstringoptional

The id of one of your own generations, the random segment of its download URL, as list_recent_generations and get_generations return it. Works while the generation is still downloadable, that is, while it still appears on your generations page. Given without sourceImage, the call fails.

sourceImagestringoptional

One of that generation's delivered filenames, as get_generations lists them, e.g. a_lotus_cradling_a_glowing_pearl.png. Given without sourceGeneration, the call fails.

A sourced reference is the image as generated, not as currently delivered: an edit's size, file type or background color does not carry into it. A batch generated with a reference sourced this way restarts the download window of the set it came from, and joins that set when it is made with the same tool on the same kind of background, a color or transparent. To grow a set with nothing else changed, extend_image_set, extend_character_set and extend_illustration_set do it in one call. An image larger than the reference limits is downscaled to fit; if it is still over 500KB as PNG, it is flattened onto white and saved as JPEG, losing any transparency.

What comes back

uploadURLstring

Where to send the image file. A plain HTTP PUT of the raw file bytes: curl -T yourimage.png "<uploadURL>". Any HTTP client works.

refstring

The token to pass to any tool parameter that takes reference images. Reusable across any number of calls.

expiresAtstring

When this reference expires if it goes unused. The window restarts every time you use or re-upload it.

02 / 04 · Listing
The list tool

list_references

Lost a token? Have your client call this tool: it lists every reference still live on your API key, most recently used or uploaded first, so your AI can pick the token back up instead of uploading the image again. Free to call.

list_references
# Your AI calls the tool, no arguments needed
list_references()

# It responds with each live reference: its ref_ token,
# upload URL, expiry, and the image it was filled from, if any

What comes back

referencesarray

Your live references, most recently used or uploaded first.

totalinteger

How many references are live on your API key.

Each entry in references:

refstring

The token to pass to any tool parameter that takes reference images.

uploadURLstring

Where to upload or replace the reference's image, the same plain HTTP PUT as when it was created.

expiresAtstring

When the reference expires unless it is used or re-uploaded first.

hasImageboolean

Whether an image is in place. A slot whose upload never happened shows false; upload to its URL to use it.

sourceGeneration, sourceImagestring

The generation and image a reference was filled from, when it came from one of your own generations.

03 / 04 · Limits & lifetime
What an upload accepts, and how long it lives

A few uploads serve
a whole session

Accepted images

PNG, JPEG, or WebP. At most 500KB per image, each side between 64px and 768px. Oversized images are rejected with a clear message, resize and re-upload; larger reference images do not improve results.

Lifetime

A reference expires 7 days after its last use or re-upload: every call that uses it, and every re-upload, restarts that window. Re-uploading to the same URL replaces the image in that slot, the way to swap references without creating more.

Private and reusable

References are private to your API key and reusable across any number of calls and tools. Keep up to 10 live at once; minting past that recycles your least recently used slot.

04 / 04 · Deleting
The delete tool

delete_references

A reference you stop using expires on its own. To remove some sooner, say images you would rather not leave on a server, have your client call this tool with their tokens. There is no undo.

delete_references
# Your AI calls the tool with the tokens to remove
delete_references(refs: ["ref_abc123"])

# Each reference's image is deleted, and its token
# stops working in any later call
refsstring[]required

The ref_ tokens of the references to delete, as create_reference or list_references returned them. Up to 50 per call.

What comes back

deletedstring[]

The tokens that were deleted.

notFoundstring[]

Tokens not found for your API key, or already expired; nothing was deleted for them. Listed here only when at least one token was deleted; when none was, the call fails with an error naming them.