Home
Logospell · Docs

Recent generations tools

Nothing is lost to a dropped connection: list_recent_generations returns your recent generations with their download links, get_generations returns specific ones in full, and delete_generations removes them. All three are free.

scroll ↓
01 / 03 · How it works
The recovery tool

list_recent_generations

If the connection drops before a result message arrives, the generation may still have completed, and generations are billed when they finish, not when the message lands. Have your client call this tool and it returns your recent generations, newest first, each with its download URL, so the work is recovered rather than repeated. Each row is a short index entry; a generation's full record, its prompt.json included, comes from get_generations below.

list_recent_generations
# Your AI calls the tool
list_recent_generations(limit: 5)

# It responds with your recent generations, newest first,
# each with its tool, style or character, and a download URL for its zip
limitintegeroptional

Maximum number of generations to return. With offset it pages through your generations, newest first; total in the response says how many there are.

Default: 5
offsetintegeroptional

How many of the newest generations to skip before returning up to limit of them. The two oldest are limit: 2 at an offset of total minus 2.

Default: 0

What comes back

generationsobject[]

Your recent generations, newest first, one entry each as below.

totalinteger

How many unexpired generations your key has in all. More than offset plus the entries returned means there are more to page through.

Each entry in generations:

idstring

The random segment of its download URL. get_generations, delete_generations, edit_set, export_set, the extend tools and create_reference's sourceGeneration take it.

toolstring

The tool that made it.

createdstring

When it was generated.

expiresAtstring

When its download window closes.

zipURLstring

The download URL of its zip, the same one the generation returned.

style, characterstring

A set's style, or a character set's character text, as written. Absent when it came from reference images alone.

imagesinteger

How many images it delivered.

deliveredAtstring

When the current delivery was cut: the generation time, or the last edit.

editedboolean

true when edit_set has changed its delivery from what was generated.

editableboolean

true when edit_set can deliver it again.

crispBaseSizeinteger

The largest base size, in pixels, at which export_set keeps every density crisp; absent when none does. For an illustration set, a quarter of the longest side its scenes were drawn at, and the largest it exports at.

parentsstring[]

Ids of the generations this one came from: for a batch made with an extend tool, its set's first batch; otherwise the generations its sourced references were copied from (create_reference's sourceGeneration). Only a parent made by the same tool on the same kind of background, a color or transparent, is in this one's set; any other only supplied reference images. To gather a whole set's ids, follow only those (get_generations' promptJSON shows each one's tool and background).

A generation stays downloadable for 30 days from when it is made, and re-listing does not extend that. A batch made with extend_image_set, extend_character_set or extend_illustration_set restarts the window for the whole set, and so does using one of its images as a reference for another generation (create_reference with sourceGeneration). Have your client fetch the zip promptly once recovered.

The generations page shows each set's deadline and hands its link back; see it on the site in the tutorials.

Your generations
02 / 03 · Fetching
The lookup tool

get_generations

When your AI already has a generation's id, from a download link or a set's lineage, this tool returns that generation's full record, so the generation can be extended or reproduced. Free to call.

get_generations
# Your AI calls the tool with ids it already has
get_generations(generations: ["a268ab1a725cc8a9ab43bd34", "5d2c9e04b8a1f37e6c0b9d42"])

# It responds with each generation's full record: its download
# link and expiry, current delivery settings, and its prompt.json
generationsstring[]required

The ids of the generations to get: the random segment of each one's download URL. Up to 50 per call; ids that are not found, or whose download window has closed, come back in notFound, and the call fails only when none is found.

What comes back

generationsobject[]

The generations found, in the order you asked for them, one full record each as below.

notFoundstring[]

Ids that were not found for your key or whose download window has closed. Absent when every id was found.

Each entry in generations, its full record:

id, created, expiresAt, zipURLstring

As list_recent_generations returns them.

promptJSONobject

The prompt.json its zip holds, verbatim. What it asked for (its style or character, its subjects, variations or scenes, and its references) is the original call's; its delivery settings are the current ones, after any edits, so reusing it reproduces the set as it stands now. An image or character set's background is the color it was generated on, or transparent; a set generated transparent stays transparent here after an edit changes its background to a color, and levers holds the color.

leversobject

The delivery settings now in force: width, height, canvas, minimumMargin, sizing, format, quality, background and, when a file size limit is set, maxKB, or for an illustration set width, height, format and quality. Absent on sets from before editing existed.

referencesobject[]

Where each reference image came from, in call order: from and image (what create_reference takes as sourceGeneration and sourceImage), or uploaded for a hand-uploaded file. Absent when none were used.

nativeWidth, nativeHeightinteger

The canvas the set would be delivered on at native size, with no width or height fixed. For an illustration set, the size its scenes were drawn at, the largest they can be delivered at.

deliveredAtstring

When the current delivery was cut: the generation time, or the last edit.

editedboolean

true when edit_set has changed its delivery from what was generated.

editableboolean

true when edit_set can deliver it again.

crispBaseSizeinteger

The largest base size, in pixels, at which export_set keeps every density crisp; absent when none does. For an illustration set, a quarter of the longest side its scenes were drawn at, and the largest it exports at.

parentsstring[]

Ids of the generations this one came from: for a batch made with an extend tool, its set's first batch; otherwise the generations its sourced references were copied from (create_reference's sourceGeneration). Only a parent made by the same tool on the same kind of background, a color or transparent, is in this one's set; any other only supplied reference images. To gather a whole set's ids, follow only those (get_generations' promptJSON shows each one's tool and background).

03 / 03 · Deleting
The delete tool

delete_generations

Every generation is removed on its own when its download window closes, 30 days after it is made or after its window last restarts. To remove some sooner, have your client call this tool with their ids: each one's download URL stops working at once, and its images and the full-resolution source kept for edits and exports are deleted from Logospell's servers. Only the API key that made a generation can delete it. There is no undo, and the credits they cost are not refunded. Free to call.

delete_generations
# Your AI calls the tool with ids from list_recent_generations
delete_generations(generations: ["a268ab1a725cc8a9ab43bd34"])

# Each generation's download URL stops working, and its images
# and the source kept for edits and exports are removed
generationsstring[]required

The ids of the generations to delete: the random segment of each one's download URL, as list_recent_generations returns it. A set that grew over several calls has one id per call; pass them all to delete the whole set. Up to 50 per call; ids that are not found, or whose download window has closed, come back in notFound, and the call fails only when none is deleted.

What comes back

deletedstring[]

The ids that were deleted.

notFoundstring[]

Ids that were not found for your key or whose download window had closed; nothing was deleted for them. Absent when every id was deleted.

The generations page has a Delete on each set too: it passes every generation in the set to this same tool.