Model APIs

Upload a file once, keep its asset id, and reuse it as a reference. Uploaded media lives in the same Library as generated media and can be filed into a project.

Two ways to upload #

The base64 route returns a stored asset immediately. The signed route first creates an uploading asset; only completion verifies the bytes and makes it ready. The CLI's upload command selects the upload flow for the file.

Small files #

These are examples, not live upload captures. Set NOLGIA_TOKEN as in the Quick Start and replace reference.png with a small local image. The curl command uses macOS base64 -i; on GNU systems use base64 reference.png. Rust also uses the base64 crate for encoding.

$ curl -sS https://api.nolgia.ai/v1/assets \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content_type":"image/png","filename":"reference.png","data":"<the file, base64-encoded>"}'

$ nolgia --json assets upload reference.png

import { readFile } from "node:fs/promises";
import { createNolgiaClient } from "@nolgia/sdk";

const nolgia = createNolgiaClient(process.env.NOLGIA_TOKEN!);
const { data: asset, error } = await nolgia.POST("/assets", {
  body: {
    content_type: "image/png",
    filename: "reference.png",
    data: (await readFile("reference.png")).toString("base64"),
  },
});
if (error) throw new Error(`${error.title}: ${error.detail ?? ""}`);
console.log(asset.id);

import base64
import os
from pathlib import Path
from nolgia import AuthenticatedClient
from nolgia.api.assets import upload_asset
from nolgia.models import Asset, UploadAssetRequest

client = AuthenticatedClient(base_url="https://api.nolgia.ai/v1", token=os.environ["NOLGIA_TOKEN"])
asset = upload_asset.sync(client=client, body=UploadAssetRequest.from_dict({
    "content_type": "image/png",
    "filename": "reference.png",
    "data": base64.b64encode(Path("reference.png").read_bytes()).decode("ascii"),
}))
if not isinstance(asset, Asset):
    raise SystemExit(f"refused: {asset}")
print(asset.id)

use base64::{engine::general_purpose::STANDARD, Engine};
use nolgia_client::ClientBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClientBuilder::new("https://api.nolgia.ai/v1")
        .bearer_token(std::env::var("NOLGIA_TOKEN")?)
        .build()?;
    let encoded = STANDARD.encode(std::fs::read("reference.png")?);
    let asset = client.upload_asset()
        .body_map(|b| b.content_type("image/png").data(encoded))
        .send().await?.into_inner();
    println!("{}", asset.id);
    Ok(())
}

The HTTP response is an Asset; this schema-built excerpt shows a stored image. The snippets print its reusable id. The omitted model field records upload provenance, not a generation model from the catalog.

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

Large files, step by step #

1. Create the upload #

For a local final-cut.mp4, measure the size instead of estimating it. Keep the response in upload for the next two calls.

$ curl -sS https://api.nolgia.ai/v1/assets/uploads \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"final-cut.mp4","content_type":"video/mp4","size_bytes":<the exact file size in bytes>}'

{
  "upload_id": "33333333-3333-4333-8333-333333333333",
  "asset_id": "44444444-4444-4444-8444-444444444444",
  "upload_url": "https://storage.googleapis.com/example/final-cut.mp4?…",
  "expires_at": "2026-09-21T04:00:00Z"
}

2. PUT the bytes #

$ curl -sS -X PUT "<upload_url from the response>" -H "Content-Type: video/mp4" --upload-file final-cut.mp4

HTTP/1.1 200 OK
Content-Length: 0

The successful storage PUT has no JSON body. It does not complete the asset; the API still needs the verification call below.

3. Complete the asset #

$ curl -sS -X POST "https://api.nolgia.ai/v1/assets/uploads/<upload_id from the response>/complete" -H "Authorization: Bearer $NOLGIA_TOKEN"

{
  "id": "44444444-4444-4444-8444-444444444444",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "modality": "video",
  "mime_type": "video/mp4",
  "signed_url": "https://storage.googleapis.com/example/final-cut.mp4?…",
  "expires_at": "2026-09-21T05:00:00Z",
  "status": "ready",
  "created_at": "2026-09-21T03:30:00Z"
}

Default GET /assets listings hide unfinished uploads. Media duration, audio detection and thumbnails may arrive later through the media sweep; ready does not mean every optional metadata field is already populated.

Using your own storage #

Pass your own HTTPS URL to a request's supported *_url field, or a Library asset id to its *_asset_id / *_asset_ids field. The URL must remain reachable when processing starts. Reference support still depends on the model; see Common model arguments.

These two image request bodies illustrate the same choice. Use a reference-capable model and replace the URL or id with your own.

{
  "model": "gpt-image-2",
  "prompt": "Place this product on a plain white background",
  "image_url": "https://media.example.com/product.png"
}

{
  "model": "gpt-image-2",
  "prompt": "Place this product on a plain white background",
  "reference_asset_ids": ["11111111-1111-4111-8111-111111111111"]
}

Both submit a job. This schema-built response applies to either request; follow the id with submit and poll.

{
  "id": "55555555-5555-4555-8555-555555555555",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "modality": "image",
  "model": "gpt-image-2",
  "status": "queued",
  "created_at": "2026-09-21T03:30:00Z",
  "updated_at": "2026-09-21T03:30:00Z"
}

Upload details #

Accepted MIME types for signed uploads are generated from the request schema:

• video/mp4
• video/quicktime
• video/webm
• audio/mpeg
• audio/wav
• audio/ogg
• audio/webm
• audio/mp4
• image/png
• image/jpeg
• image/webp
• model/gltf-binary

Google Drive #

Import a media file into the Library or export an asset to Google Drive. Both calls use a short-lived Google OAuth token with the drive.file scope for that request only. Import accepts the signed-upload media types and size limits; Google Docs, Sheets, and Slides are not media imports. These calls are available on Studio plans, Team, and Enterprise.

Expiry and access #

Upload URLs and download URLs have different lifetimes. Read Storage and data retention for signed URL renewal and deletion, and File access controls for Library scope and share links that remain useful after a download URL expires.