Model APIs

Keep asset ids in your application and fetch download URLs when you need them. A signed URL's expiry controls access to the bytes; it is separate from when the asset is deleted.

Generated media #

Uploaded and generated assets are stored in Google Cloud Storage (GCS). signed_url is stable for about an hour: reads within the same clock hour return the same signed URL so the media can be cached across refreshes. Each asset read signs for the current window, with at least one hour of validity remaining; expires_at reports the real expiry.

Optional media metadata can lag behind the bytes. Uploaded or older videos may have no duration, audio verdict or poster until the asynchronous media sweep has inspected them. A missing thumbnail_url is not a failed asset.

Request payloads #

The asset stores the prompt. For images, prompt preserves the customer's words; enhanced_prompt contains the composed prompt that actually ran when it differs. For video and audio, prompt is the dispatched prompt and enhanced_prompt is absent or null. Uploaded assets may have no prompt.

There is no switch to stop storing prompts and no per-request expiry header.

Trash and deletion #

The lifecycle is live → trash → permanent deletion. DELETE /assets/{id} moves an asset to trash and keeps its stored bytes for recovery. The API purges trashed assets 30 days after deleted_at, or you can call the permanent-delete endpoint earlier.

The trash filter is trashed=true. The separate status parameter chooses uploading or ready; it does not select trash. Deleting an already-trashed asset returns 404.

Move an asset to trash and restore it #

These examples perform both operations in order. The CLI supports assets delete; it has no restore command, so its tab uses the HTTP restore call. The Rust example configures an empty-body Content-Length for the generated bodyless POST.

$ curl --fail-with-body -sS -X DELETE "https://api.nolgia.ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"
$ curl --fail-with-body -sS -X POST "https://api.nolgia.ai/v1/assets/$ASSET_ID/restore" \
  -H "Authorization: Bearer $NOLGIA_TOKEN" --data ''

$ nolgia assets delete "$ASSET_ID"
$ curl --fail-with-body -sS -X POST "https://api.nolgia.ai/v1/assets/$ASSET_ID/restore" \
  -H "Authorization: Bearer $NOLGIA_TOKEN" --data ''

import { createNolgiaClient } from "@nolgia/sdk";

const nolgia = createNolgiaClient(process.env.NOLGIA_TOKEN!);
const params = { path: { id: process.env.ASSET_ID! } };
const { error: deleteError } = await nolgia.DELETE("/assets/{id}", { params });
if (deleteError) throw new Error(`${deleteError.title}: ${deleteError.detail ?? ""}`);
const { data: asset, error } = await nolgia.POST("/assets/{id}/restore", { params });
if (error) throw new Error(`${error.title}: ${error.detail ?? ""}`);
console.log(asset.id, asset.signed_url);

import os
from http import HTTPStatus
from uuid import UUID
from nolgia import AuthenticatedClient
from nolgia.api.assets import delete_asset, restore_asset
from nolgia.models import Asset

client = AuthenticatedClient(base_url="https://api.nolgia.ai/v1", token=os.environ["NOLGIA_TOKEN"])
asset_id = UUID(os.environ["ASSET_ID"])
deleted = delete_asset.sync_detailed(asset_id, client=client)
if deleted.status_code != HTTPStatus.NO_CONTENT:
    raise SystemExit(f"refused: {deleted.parsed}")
asset = restore_asset.sync(asset_id, client=client)
if not isinstance(asset, Asset):
    raise SystemExit(f"refused: {asset}")
print(asset.id, asset.signed_url)

use nolgia_client::Client;
use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION, CONTENT_LENGTH};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut headers = HeaderMap::new();
    headers.insert(AUTHORIZATION, HeaderValue::from_str(
        &format!("Bearer {}", std::env::var("NOLGIA_TOKEN")?),
    )?);
    headers.insert(CONTENT_LENGTH, HeaderValue::from_static("0"));
    let http = reqwest::Client::builder().default_headers(headers).build()?;
    let client = Client::new_with_client("https://api.nolgia.ai/v1", http);
    let id = std::env::var("ASSET_ID")?.parse::<uuid::Uuid>()?;
    client.delete_asset().id(id).send().await?;
    let asset = client.restore_asset().id(id).send().await?.into_inner();
    println!("{} {}", asset.id, asset.signed_url);
    Ok(())
}

Deletion returns 204 No Content, with no JSON. Restoration returns an asset; this is a schema-built excerpt, not a captured restore. The omitted model field records upload provenance for this uploaded image.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "modality": "image",
  "signed_url": "https://storage.googleapis.com/example/reference.png?…",
  "expires_at": "2026-09-21T05:00:00Z",
  "status": "ready",
  "created_at": "2026-09-20T03:30:00Z"
}

Bring your own storage #

Enterprise organizations can connect an S3-compatible bucket. An owner or admin creates the connection, tests its credentials, and enables mirroring so assets are copied as they become ready. Existing ready assets can be backfilled, and objects in the bucket can be imported into the Library. The original Nolgia asset remains the id you use with the API.

mirrors is present only for an organization asset with at least one storage connection. Each entry names the connection, its copy status and, once available, the remote object key. Read that status before assuming the copy has completed.

Summary #