Skip to Content
API referenceModels

Models

The performer roster — create and curate models, upload reference images, and read the scenes and frame-matches they appear in. Reads need models:read; writes need models:write.

List models with filters + sort.

models:read
GET/v1/models
Parameters
q
string
Free-text name/alias search.
status
"active" | "inactive" | "all"
Filter by active status.
hasScenes
"any" | "with" | "without"
Filter by whether the model has scenes.
studio
string
Filter by studio attribution.
sort
"newest" | "most-scenes" | "alphabetical"
Sort order.
limit
integer
Items per page.
offset
integer
Offset for pagination.
Response fields
items
Model[]
The page of models (see the Model object).
total
integer
Total matching models.
limit
integer
Items per page.
offset
integer
Current offset.
GET/v1/models
Request
GET /v1/models?status=active&sort=most-scenes&limit=2
Response
Press Run request to see the response

Get a model by slug.

models:read
GET/v1/models/{slug}
Parameters
slug
string · required
Model slug.

Returns the full Model object — see the Model object.

GET/v1/models/{slug}
Request
GET /v1/models/bella-luna
Response
Press Run request to see the response

Create a model.

models:write
POST/v1/models
Console roles: OWNER, DIRECTOR
Request body
name
string · required
Display name.
slug
string
Workspace-scoped slug; auto-derived from name if omitted.
aliases
string[]
Alternate names.
active
boolean
Active (vs archived) status.
studio
string
Studio attribution.
records2257
boolean
§2257 record on file.

Returns the created Model object.

Update a model (slug not patchable).

models:write
PATCH/v1/models/{slug}
Console roles: OWNER, DIRECTOR
Parameters
slug
string · required
Model slug.
Request body
name
string
Display name.
aliases
string[]
Alternate names.
imageUrl
string
Public cover-image URL.
imageKey
string
Storage key for the cover image.
active
boolean
Active (vs archived) status.
studio
string
Studio attribution.
records2257
boolean
§2257 record on file.

Returns the updated Model object.

Soft-delete a model (scenes preserved).

models:write
DELETE/v1/models/{slug}
Console roles: OWNER, DIRECTOR
Parameters
slug
string · required
Model slug.
Response fields
deleted
boolean
True if deleted.
hard
boolean
Whether the delete was a hard delete.
scenesPreserved
boolean
True — linked scenes are kept.
alreadyDeleted
boolean
True if the model was already deleted.

Upload a reference image (raw image body).

models:write
POST/v1/models/{slug}/image
Console roles: OWNER, DIRECTOR
Parameters
slug
string · required
Model slug.
Response fields
imageUrl
string
Public cover-image URL.
imageKey
string
Storage key for the image.
imageWidth
integer
Image width in pixels.
imageHeight
integer
Image height in pixels.
imageBytes
integer
Image size in bytes.
imageFaceCheckStatus
string
Face-detection check status.
warnings
string[]
Non-fatal warnings.
Send the raw image bytes as the request body with the matching Content-Type (e.g. image/webp).

Scenes a model appears in (cursor-paginated).

models:read
GET/v1/models/{slug}/scenes
Parameters
slug
string · required
Model slug.
limit
integer
Items per page.
cursor
string
Cursor from a previous page.
Response fields
items
object[]
The page of scenes.
cursor
string | null
Next cursor.
hasMore
boolean
True if more pages exist.

Frame-match previews (offset-paginated, confidence desc).

models:read
GET/v1/models/{slug}/frames
Parameters
slug
string · required
Model slug.
limit
integer
Items per page.
offset
integer
Offset for pagination.
Response fields
items
object[]
Frame matches: { url, offsetSec, confidence, sceneId }.
total
integer
Total frame matches.

Model event timeline (cursor-paginated).

models:read
GET/v1/models/{slug}/activity
Parameters
slug
string · required
Model slug.
limit
integer
Items per page.
cursor
string
Cursor from a previous page.
Response fields
items
object[]
Timeline entries.
cursor
string | null
Next cursor.
hasMore
boolean
True if more pages exist.

Check slug availability.

models:write
POST/v1/models/check-slug
Request body
slug
string · required
Candidate slug.
excludeModelId
string
Model ID to exclude (when renaming).
Response fields
available
boolean
True if the slug is free.
reason
"taken" | "reserved" | "invalid"
Why unavailable (optional).

Probe image dimensions (raw image body, no DB write).

models:write
POST/v1/models/check-image
Response fields
width
integer | null
Detected width in pixels.
height
integer | null
Detected height in pixels.
bytes
integer
Image size in bytes.
ok
boolean
True if the image is usable.
warnings
string[]
Non-fatal warnings.

Download the CSV import template.

models:read
GET/v1/models/import/template.csv

Returns a text/csv template file.

Get the in-flight import for this workspace, or null.

models:read
GET/v1/models/import
Response fields
id
string
Import ID.
status
"PREVIEW" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELED"
Import status.
kind
string
Import kind.
filename
string
Uploaded filename.
totalRows
integer
Total rows in the file.
readyRows
integer
Rows that validated cleanly.
warningRows
integer
Rows with warnings.
errorRows
integer
Rows with errors.
committedRows
integer
Rows already committed.
rows
object[]
Per-row validation detail.

Get one import + its rows.

models:read
GET/v1/models/import/{id}
Parameters
id
string · required
Import ID.

Same shape as GET /v1/models/import.

Upload a CSV (raw text/csv body) → creates a PREVIEW import with per-row validation.

models:write
POST/v1/models/import/csv
Console roles: OWNER, DIRECTOR
Response fields
id
string
Import ID.
status
string
"PREVIEW".
totalRows
integer
Total rows in the file.
readyRows
integer
Rows that validated cleanly.
warningRows
integer
Rows with warnings.
errorRows
integer
Rows with errors.
rows
object[]
Per-row validation detail.
Send the CSV as the raw request body (Content-Type: text/csv). Columns: name (required), slug, aliases (semicolon-delimited), reference_image_url (required), active, studio.

Commit an import (PREVIEW → PROCESSING).

models:write
POST/v1/models/import/{id}/apply
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Import ID.
Request body
skipWarnings
boolean
Commit rows that only carry warnings.
rowIds
string[]
Specific rows to commit; omit for all eligible.
Response fields
id
string
Import ID.
status
string
"PROCESSING".
startedAt
string (ISO)
When processing began.
committedRows
integer
Rows committed.

Cancel an import; committed rows kept, the rest skipped.

models:write
POST/v1/models/import/{id}/cancel
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Import ID.
Response fields
id
string
Import ID.
status
string
"CANCELED".
canceledAt
string (ISO)
When it was canceled.
committedRows
integer
Rows kept.
skippedRows
integer
Rows skipped.
Last updated on
Scenes§2257 records