Skip to content

Public Media API

Provider-neutral /v1 media catalog, estimates, generation, history, and recommendations.

Public media lives under /v1/media. Every operation uses an organization API key and a named account rate policy. Responses never include provider names, endpoints, or provider filenames.

MethodPathRequestResponse
GET/v1/media/models—MediaModelList
GET/v1/media/recommendationsintent queryMediaModelList
POST/v1/media/estimatesMediaEstimateRequestMediaEstimate
POST/v1/media/generationsMediaGenerationRequest, Idempotency-KeyMediaGeneration
GET/v1/media/generationslimit queryMediaGenerationList
GET/v1/media/generations/{generation_id}path parameterMediaGeneration
GET /v1/media/models
Terminal window
curl https://api.dexto.ai/v1/media/models \
-H "Authorization: Bearer $DEXTO_API_KEY"
Response fieldJSON typeRequiredDescription
object"list"YesList discriminator
dataarray<media.model>YesReviewed models this deployment can run
GET /v1/media/recommendations

intent is a trimmed string of 1–2000 characters. The response uses the same media.model objects as the catalog list.

Terminal window
curl "https://api.dexto.ai/v1/media/recommendations?intent=cinematic%20product%20video" \
-H "Authorization: Bearer $DEXTO_API_KEY"
POST /v1/media/estimates
Terminal window
curl https://api.dexto.ai/v1/media/estimates \
-H "Authorization: Bearer $DEXTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "image.quality",
"input": { "prompt": "A precise exploded diagram of a mechanical keyboard" }
}'

A generation is Cloud usage of your key’s project, charged at the provider’s cost plus 25%: amount_usd is that charge, and pricing.unit_price_usd is the provider’s price.

POST /v1/media/generations
Terminal window
curl https://api.dexto.ai/v1/media/generations \
-H "Authorization: Bearer $DEXTO_API_KEY" \
-H "Idempotency-Key: $REQUEST_ID" \
-H "Content-Type: application/json" \
-d '{"estimate_id":"724df530-01e7-45f6-a73b-756401b51d31"}'

The estimate is single-use. Reuse the same Idempotency-Key when retrying. Incomplete work returns 202; completed work returns 200 with the same media.generation object.

FieldJSON typeRequiredDescription
estimate_idstringYesThe estimate to generate
save_tostringNoSave the outputs as project files: a file path, or a prefix ending in /
overwritebooleanNoReplace a file already at a save_to path; default false
GET /v1/media/generations

limit defaults to 20 and must be an integer from 1 to 100. When has_more is true, pass the response’s next_after as after for the next page; the older next_cursor carries the same value and is deprecated. Each item is the same object as GET /v1/media/generations/{generation_id}. Only completed generations with Dexto artifacts are included: the caller’s own and, for a developer or deployment key, every generation of its Cloud project, such as those its agents made. Stored artifact details that cannot be loaded do not fail the list: filename, mime_type and url are null while uri, id, and kind remain.

Each resource has a url: a signed link that downloads the output without an API key, minted on every read and valid until url_expires_at (at most an hour). Read the generation again for a fresh link. Hand the link to your user or fetch it from your backend.

A generation made with a developer or deployment key, or by an agent, keeps its outputs for 24 hours after it completes, until the resource’s expires_at; the storage is included in the generation’s price. After that the output is deleted, and the resource shows expired: true with no url. Keep an output by downloading it, or by saving it into your project’s files with save_to. Generations made in the Dexto app or with CLI keys keep their outputs (expires_at is null).

Terminal window
curl "https://api.dexto.ai/v1/media/generations?limit=20" \
-H "Authorization: Bearer $DEXTO_API_KEY"
{
"object": "list",
"data": [
{
"object": "media.generation",
"id": "b8698bf3-df63-4c31-bdec-929fd0c9104e",
"model": "video.text.seedance-2",
"media_kind": "video",
"status": "settled",
"completed": true,
"resources": [
{
"id": "owned-clip-1",
"file_id": null,
"file_path": null,
"filename": "generated-video-1.mp4",
"kind": "video",
"mime_type": "video/mp4",
"uri": "artifact://session/account%3Auser/owned-clip-1",
"url": "https://app.dexto.ai/api/artifact-exports/eyJhbGciOi…",
"url_expires_at": "2026-09-13T11:03:19.000Z",
"expires_at": "2026-09-14T10:03:19.000Z",
"expired": false
}
],
"error": null,
"save": null,
"created_at": "2026-09-13T10:00:00.000Z",
"updated_at": "2026-09-13T10:03:21.000Z",
"completed_at": "2026-09-13T10:03:19.000Z"
}
]
}
GET /v1/media/generations/{generation_id}

Reads one owned generation, or one of the key’s Cloud project, including run-scoped artifacts stored under the operation’s own session (and desktop, when the object key includes one). Any other generation returns the standard not-found envelope.

FieldJSON typeRequiredDescription
idstringYesStable Dexto generation ID
modelstringYesPublic media model ID
media_kindstringYesaudio, file, image, or video
statusstringYesDurable operation state
resourcesarrayYesFinalized Dexto artifacts
resources[].uristringYesDexto artifact URI
resources[].idstringYesArtifact ID from the owned URI
resources[].filenamestring | nullYesProvider-neutral filename; null if stored details cannot be loaded
resources[].kindstringYesaudio, binary, image, or video
resources[].mime_typestring | nullYesStored media type; null if stored details cannot be loaded
resources[].urlstring | nullYesSigned download link minted on this read; null once expired
resources[].url_expires_atstring | nullYesWhen url stops working: at most an hour, never past expires_at
resources[].expires_atstring | nullYesWhen the output is deleted; null when it is kept
resources[].expiredbooleanYesThe output was deleted; it has no url or stored details
resources[].file_idstring | nullYesIts project file once saved
resources[].file_pathstring | nullYesThe exact path it was saved at; null until saved
errorobject | nullYesBounded failure; message is generic
saveobject | nullYesWhere the outputs are saved as files, if asked
completed_atstring | nullYesISO-8601 completion timestamp

A Cloud generation’s outputs are deleted 24 hours after it completes. To keep them in your Cloud project’s files, pass save_to when you start it, with a developer or deployment key of that project. A deployed Function’s or Site’s key that passes no save_to keeps them under artifacts/, where cloud.artifacts reads them:

{ "estimate_id": "724df530-01e7-45f6-a73b-756401b51d31", "save_to": "renders/" }
  • A prefix ending in / saves each output as <prefix><output id>.<extension>.
  • A file path saves the first output there, and any others with -2, -3… before the extension.
  • A path that already holds a file is 409 unless overwrite is true.

save_to is checked before the generation starts: 403 for a key outside a Cloud project, 400 for a path that breaks the path rules, 409 for a taken path, and 402 when the project has no credits or reached a spend limit. The outputs are copied into files as soon as they are ready, well before they expire, and are admitted, stored and charged like any other file; the files stay until you delete them.

Saving never fails the generation. Its save object tells you how it went:

FieldJSON typeDescription
tostringThe save_to you passed
overwritebooleanThe overwrite you passed
statusstringpending, saved, or failed
error_codestring | nullWhy it failed, for example conflict when the path was taken meanwhile

A save that fails for now stays pending and is retried until the outputs expire, then fails with output_expired. Each resource names its file in file_id, and the exact path it was saved at in file_path, once saved; read the path from there rather than working it out. save is null for a generation that did not ask.