Sign in

Images

List the images and videos Dramatis Studio still keeps, with signed links, for the account or for one namespace.

GET /v1/images lists the images and videos of your account that Dramatis Studio still keeps. Each item has signed links to the file and to a small copy. Use it to show a gallery without reading every task.

The list

The list is newest first, by the time each task completed. One task with several images gives one item for each image.

An image whose content has expired or was deleted is never listed. So every item has links that work. See Retention.

The list carries no prompt and no other input. Read GET /v1/tasks/{id} for those (Tasks).

Request

Filters

Field
What it does
namespace
Matches the tag exactly. The list then reads only that namespace's images.
model
One model.
task
The kind of task: generate, edit, upscale, remove_background, face_swap or image_to_video.
aspect_ratio
1:1, 2:3, 3:2, 16:9 or 9:16.
created_after
Images whose task completed after this instant, the instant itself not included.
created_before
Images whose task completed before this instant, the instant itself not included.
limit
From 1 to 100. The default is 20.
cursor
The next_cursor of the previous page.

The items

Field
Meaning
task_id
The task the image belongs to.
index
The image's position among the task's images, from 0.
url
The full image, as a signed link.
thumb_url
A small copy, as a signed link, or null if it could not be made.
model
The model that made it.
task
The kind of task.
aspect_ratio
The image's ratio, or null.
namespace
The task's namespace, or null.
created_at
When the task completed.
expires_at
When Dramatis Studio stops keeping it, or null.

url and thumb_url work for one hour. Every read of the list returns fresh links. Store the task_id, not the link, and download the file if you need it for longer than its retention.

Videos

A video task is listed too, with task set to image_to_video. Its url is the clip, an mp4 file, the same link as the task's output. Its thumb_url is the poster, the clip's first frame. See Video.

Paging

A page holds up to limit items. When there are more, next_cursor is set: pass it as cursor, with the same filters, to read the next page. On the last page next_cursor is null.

A cursor belongs to one list. A cursor of another namespace, or of the list without a namespace, is refused with 400 invalid_request.

One namespace

namespace is the tag you set on a task for one of your users, machines or services (Tasks). GET /v1/tasks?namespace= and GET /v1/images?namespace= read only that namespace, newest first. So an app can show one user's or one machine's tasks and images, without reading the rest of the account.

Request

The playground key

The playground on the model pages calls the API with a key that lasts one hour. That key sees only the images of playground and Studio tasks, not those of tasks made with your own keys.