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.
Endpoints
Section titled “Endpoints”| Method | Path | Request | Response |
|---|---|---|---|
GET | /v1/media/models | — | MediaModelList |
GET | /v1/media/recommendations | intent query | MediaModelList |
POST | /v1/media/estimates | MediaEstimateRequest | MediaEstimate |
POST | /v1/media/generations | MediaGenerationRequest, Idempotency-Key | MediaGeneration |
GET | /v1/media/generations | limit query | MediaGenerationList |
GET | /v1/media/generations/{generation_id} | path parameter | MediaGeneration |
List models
Section titled “List models”/v1/media/models curl https://api.dexto.ai/v1/media/models \ -H "Authorization: Bearer $DEXTO_API_KEY"| Response field | JSON type | Required | Description |
|---|---|---|---|
object | "list" | Yes | List discriminator |
data | array<media.model> | Yes | Reviewed models this deployment can run |
Recommend models
Section titled “Recommend models”/v1/media/recommendations intent is a trimmed string of 1–2000 characters. The response uses the same media.model objects
as the catalog list.
curl "https://api.dexto.ai/v1/media/recommendations?intent=cinematic%20product%20video" \ -H "Authorization: Bearer $DEXTO_API_KEY"Create estimate
Section titled “Create estimate”/v1/media/estimates 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" } }'{ "object": "media.estimate", "id": "724df530-01e7-45f6-a73b-756401b51d31", "model": "image.quality", "amount_usd": 0.0525, "confidence": "exact", "expires_at": "2026-09-13T10:15:00.000Z", "explanation": "Estimated $0.05 for one auto 1024x1024 image.", "input": { "prompt": "A precise exploded diagram of a mechanical keyboard" }, "pricing": { "type": "unit", "quantity": 1, "unit": "image", "unit_price_usd": 0.042 }}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.
Start generation
Section titled “Start generation”/v1/media/generations 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.
| Field | JSON type | Required | Description |
|---|---|---|---|
estimate_id | string | Yes | The estimate to generate |
save_to | string | No | Save the outputs as project files: a file path, or a prefix ending in / |
overwrite | boolean | No | Replace a file already at a save_to path; default false |
List generations
Section titled “List generations”/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.
Download outputs
Section titled “Download outputs”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).
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 generation
Section titled “Get generation”/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.
| Field | JSON type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable Dexto generation ID |
model | string | Yes | Public media model ID |
media_kind | string | Yes | audio, file, image, or video |
status | string | Yes | Durable operation state |
resources | array | Yes | Finalized Dexto artifacts |
resources[].uri | string | Yes | Dexto artifact URI |
resources[].id | string | Yes | Artifact ID from the owned URI |
resources[].filename | string | null | Yes | Provider-neutral filename; null if stored details cannot be loaded |
resources[].kind | string | Yes | audio, binary, image, or video |
resources[].mime_type | string | null | Yes | Stored media type; null if stored details cannot be loaded |
resources[].url | string | null | Yes | Signed download link minted on this read; null once expired |
resources[].url_expires_at | string | null | Yes | When url stops working: at most an hour, never past expires_at |
resources[].expires_at | string | null | Yes | When the output is deleted; null when it is kept |
resources[].expired | boolean | Yes | The output was deleted; it has no url or stored details |
resources[].file_id | string | null | Yes | Its project file once saved |
resources[].file_path | string | null | Yes | The exact path it was saved at; null until saved |
error | object | null | Yes | Bounded failure; message is generic |
save | object | null | Yes | Where the outputs are saved as files, if asked |
completed_at | string | null | Yes | ISO-8601 completion timestamp |
Outputs as project files
Section titled “Outputs as project files”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
409unlessoverwriteistrue.
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:
| Field | JSON type | Description |
|---|---|---|
to | string | The save_to you passed |
overwrite | boolean | The overwrite you passed |
status | string | pending, saved, or failed |
error_code | string | null | Why 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.