Sessions: keep every generated asset where you can find it

Run an image model for an afternoon and you end up with two hundred files called output_0.png. Some were for the spring campaign, some were tests, and one was the hero image your team already approved. A week later nobody can tell which is which.

Sessions fix that. A session is a named folder for a piece of work. Every run you start inside it, and every file that run produces, belongs to it. You can name each asset, tag it, and pull the whole set back with one request.

How it fits together

• An endpoint is the model you launched, for example z-image-turbo on an RTX 2000 Ada.
• A session is a piece of work, like "Spring campaign" or "Customer 4821 try-on". It can span many runs and even many endpoints.
• A run is one call to the endpoint. It can belong to one session and carries an asset name and tags.
• Assets are the files a run produces. They inherit the run name and tags, so they are easy to search.

Try it in the console first

Open Inference, expand your endpoint and look at the Try it box. Pick a session from the list or press New to create one. Give the asset a name and a few tags, type a prompt and press Run.

A timer shows how long the run has been waiting. If no worker is warm, the first run after a quiet spell can take a few minutes while the model loads, and the console tells you so. You are only billed for GPU time once the job starts, and if no worker picks it up within eight minutes we cancel it and you pay nothing.

Finished runs show their name, session and tags. Press Rename or tag on any of them to fix a typo or mark the one that got approved.

Create a session from code

Everything in the console works through the API too. Create a session with your account API key. Tags are optional and help you filter later.

curl -X POST https://www.clockingcloud.com/v1/sessions -H "Authorization: Bearer $CLOCKINGCLOUD_API_KEY" -H "Content-Type: application/json" -d '{"name": "Spring campaign", "tags": ["client:acme", "q1"]}'

The response includes an id that starts with ses_. Keep it, you will pass it with every run.

Run your endpoint inside the session

Call your endpoint the same way you already do, and add three fields: session, label and tags. The endpoint key only works for that one endpoint, so it is safe to put in a server you do not fully control.

curl -X POST https://www.clockingcloud.com/v1/endpoints/z-image-turbo/runs -H "Authorization: Bearer $ENDPOINT_KEY" -H "Content-Type: application/json" -d '{"wait": true, "session": "ses_...", "label": "Hero banner v2", "tags": ["hero", "draft"], "input": {"prompt": "A neon city at dusk, rain on the street"}}'

With wait set to true the request holds for up to about fifty seconds. If the run is still going, you get it back with its id and state, and you can fetch it again until it is done. Files come back as signed links that expire after an hour. Fetch the run again for fresh links.

Find everything again

• GET /v1/sessions/{id} returns the session and every run in it, newest first.
• GET /v1/runs?session=ses_... lists the runs in a session with their files.
• GET /v1/runs?tag=hero finds every run with that tag across all sessions.
• PATCH /v1/runs/{id} renames a run, changes its tags or moves it to another session.

When the work is done, close the session with PATCH /v1/sessions/{id} and {"closed": true}. Closed sessions keep their runs and files but refuse new runs, so nothing gets added to an approved set by accident.

Tags on instances and volumes too

Tags are not just for runs. Instances and volumes accept the same tags through PATCH /v1/instances/{name} and PATCH /v1/volumes/{name}, so you can mark a GPU box and its volume with the same client or project. Tags are lowercase, up to twenty per resource, and can use a key:value style like client:acme.

Keeping assets when you shut down

When you terminate an endpoint, the console asks whether to keep its generated files. Leave the box unchecked and your sessions, runs and files stay available after the endpoint is gone. Check it and the files are deleted with the endpoint.

In short

1. Create a session for each piece of work.
2. Pass the session, a name and tags with every run.
3. Use the session or a tag to pull the full set back later.
4. Close the session when the work is approved.