Logospell · Docs

Reference tool

Name: Logospell MCP Server
Brand: Logospell

Upload a reference image once, or point at an image you already generated, and get a token your AI can reuse in as many calls as you like. create_reference is free.

scroll ↓

01 / 02 · How it works

One short handshake

`create_reference`

create_reference supplies your images to any Logospell tool that accepts reference images. It's a short handshake your AI can perform by itself, shown step by step below.

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 reference token 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 extending a set in its own style:

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

sourceGeneration is the id from the generation's download URL and sourceImage one of its delivered filenames; list_recent_generations shows both. Sourcing works while the generation is still downloadable, that is, while it still appears on your generations page. An image larger than the reference limits is downscaled automatically.

The tool returns three fields:

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 / 02 · 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 only if it goes unused: every generation that uses it, and every re-upload, restarts its 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.

Why not inline?

Under the hood a tool call is JSON, and an image embedded there would have to be encoded text your AI client emits character by character, slow, error-prone, and heavy on its context. The upload keeps image bytes out of the conversation entirely.