List Assets

curl --request GET \
  --url https://api.example.com/api/v1/assets \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.example.com/api/v1/assets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/assets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/assets"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/assets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "assets": [
    {
      "id": "<string>",
      "url": "<string>",
      "content_type": "<string>",
      "size": 123,
      "state": "<string>",
      "created_at": "<string>"
    }
  ],
  "pagination": {
    "limit": 123,
    "offset": 123,
    "total": 123
  }
}

GET

api

assets

List Assets

curl --request GET \
  --url https://api.example.com/api/v1/assets \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.example.com/api/v1/assets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/assets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/assets"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/assets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "assets": [
    {
      "id": "<string>",
      "url": "<string>",
      "content_type": "<string>",
      "size": 123,
      "state": "<string>",
      "created_at": "<string>"
    }
  ],
  "pagination": {
    "limit": 123,
    "offset": 123,
    "total": 123
  }
}

Overview

Get a list of all assets you’ve uploaded to Babou. Supports pagination and filtering by content type and state.

Request

Headers

string

required

Bearer token with your API key: Bearer sk-bab-your-api-key

Query Parameters

number

default:"20"

Number of assets to return per page (max: 100)

number

default:"0"

Number of assets to skip for pagination

string

Filter by MIME type (e.g., image/png, video/mp4)

string

Filter by state: uploading, ready, or failed

Response

array

Array of asset objects

Show Asset object

string

Unique identifier for the asset

string

Public URL to access the asset

string

MIME type of the file

number

File size in bytes

string

Current state: uploading, ready, or failed

string

ISO 8601 timestamp

object

Pagination metadata

Show Pagination object

number

Items per page

number

Items skipped

number

Total number of assets matching the filters

Examples

# List all assets
curl https://api.babou.ai/api/v1/assets \
  -H "Authorization: Bearer $BABOU_API_KEY"

# List with pagination
curl "https://api.babou.ai/api/v1/assets?limit=50&offset=100" \
  -H "Authorization: Bearer $BABOU_API_KEY"

# Filter by content type
curl "https://api.babou.ai/api/v1/assets?contentType=video/mp4" \
  -H "Authorization: Bearer $BABOU_API_KEY"

# Filter by state
curl "https://api.babou.ai/api/v1/assets?state=ready" \
  -H "Authorization: Bearer $BABOU_API_KEY"

interface ListAssetsOptions {
  limit?: number;
  offset?: number;
  contentType?: string;
  state?: 'uploading' | 'ready' | 'failed';
}

async function listAssets(options: ListAssetsOptions = {}) {
  const params = new URLSearchParams();

  if (options.limit) params.append('limit', options.limit.toString());
  if (options.offset) params.append('offset', options.offset.toString());
  if (options.contentType) params.append('contentType', options.contentType);
  if (options.state) params.append('state', options.state);

  const response = await fetch(
    `https://api.babou.ai/api/v1/assets?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.BABOU_API_KEY}`
      }
    }
  );

  return await response.json();
}

// List all assets
const allAssets = await listAssets();

// List only videos
const videos = await listAssets({ contentType: 'video/mp4' });

// Paginate through assets
const page2 = await listAssets({ limit: 20, offset: 20 });

console.log(`Found ${allAssets.pagination.total} total assets`);
console.log(`First asset: ${allAssets.assets[0]?.url}`);

import os
import requests
from typing import Optional

def list_assets(
    limit: Optional[int] = None,
    offset: Optional[int] = None,
    content_type: Optional[str] = None,
    state: Optional[str] = None
):
    params = {}
    if limit: params['limit'] = limit
    if offset: params['offset'] = offset
    if content_type: params['contentType'] = content_type
    if state: params['state'] = state

    response = requests.get(
        'https://api.babou.ai/api/v1/assets',
        headers={'Authorization': f'Bearer {os.environ["BABOU_API_KEY"]}'},
        params=params
    )

    return response.json()

# List all assets
all_assets = list_assets()

# List only videos
videos = list_assets(content_type='video/mp4')

# Paginate through assets
page_2 = list_assets(limit=20, offset=20)

print(f'Found {all_assets["pagination"]["total"]} total assets')
print(f'First asset: {all_assets["assets"][0]["url"] if all_assets["assets"] else "None"}')

Response Example

{
  "assets": [
    {
      "id": "ast_abc123xyz456789012",
      "name": "logo.png",
      "url": "s3://babou-assets/assets/ast_abc123xyz456789012-original",
      "content_type": "image/png",
      "size": 245678,
      "state": "ready",
      "duration": null,
      "width": 1920,
      "height": 1080,
      "created_at": "2025-12-02T10:00:00Z"
    },
    {
      "id": "ast_def456uvw987654321",
      "name": "intro.mp4",
      "url": "s3://babou-assets/assets/ast_def456uvw987654321-original",
      "content_type": "video/mp4",
      "size": 15234567,
      "state": "ready",
      "duration": 45.2,
      "width": 1920,
      "height": 1080,
      "created_at": "2025-12-02T09:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 42
  }
}

Pagination

To iterate through all assets, use the offset parameter:

async function getAllAssets() {
  const allAssets = [];
  let offset = 0;
  const limit = 100; // Max per page

  while (true) {
    const response = await listAssets({ limit, offset });
    allAssets.push(...response.assets);

    if (allAssets.length >= response.pagination.total) {
      break;
    }

    offset += limit;
  }

  return allAssets;
}

const assets = await getAllAssets();
console.log(`Retrieved all ${assets.length} assets`);

def get_all_assets():
    all_assets = []
    offset = 0
    limit = 100  # Max per page

    while True:
        response = list_assets(limit=limit, offset=offset)
        all_assets.extend(response['assets'])

        if len(all_assets) >= response['pagination']['total']:
            break

        offset += limit

    return all_assets

assets = get_all_assets()
print(f'Retrieved all {len(assets)} assets')

Filtering Examples

Get all images

const images = await listAssets({ contentType: 'image/png' });
// Or filter for any image type in your application
const allImages = (await listAssets()).assets.filter(
  asset => asset.content_type.startsWith('image/')
);

Get all videos

videos = list_assets(content_type='video/mp4')

# Or filter for any video type
all_assets = list_assets()
all_videos = [
    asset for asset in all_assets['assets']
    if asset['content_type'].startswith('video/')
]

Check for failed uploads

const failedUploads = await listAssets({ state: 'failed' });

if (failedUploads.assets.length > 0) {
  console.warn(`Found ${failedUploads.assets.length} failed uploads`);
  // Retry or clean up failed uploads
}

Find recent uploads

from datetime import datetime, timedelta

assets = list_assets(limit=100)
one_hour_ago = datetime.now() - timedelta(hours=1)

recent = [
    asset for asset in assets['assets']
    if datetime.fromisoformat(asset['created_at'].replace('Z', '+00:00')) > one_hour_ago
]

print(f'Found {len(recent)} assets uploaded in the last hour')

Next Steps

Upload Asset

Upload a new asset

Get Asset

Retrieve specific asset details

Asset Management Guide

Learn how to use assets in your videos

Overview

Assets

Projects

Chapters

Prompts

Exports

List Assets

Overview

Request

Headers

Query Parameters

Response

Examples

Response Example

Filtering Examples

Next Steps

Upload Asset

Get Asset

Asset Management Guide

​Overview

​Request

​Headers

​Query Parameters

​Response

​Examples

​Response Example

​Pagination

​Filtering Examples

​Next Steps

Upload Asset

Get Asset

Asset Management Guide

Overview

Request

Headers

Query Parameters

Response

Examples

Response Example

Pagination

Filtering Examples

Next Steps