Skip to main content
GET
/
api
/
v1
/
assets
/
{assetId}
Get Asset
curl --request GET \
  --url https://api.example.com/api/v1/assets/{assetId} \
  --header 'Authorization: <authorization>'
{
  "id": "<string>",
  "name": "<string>",
  "url": {},
  "content_type": "<string>",
  "size": {},
  "state": "<string>",
  "duration": {},
  "width": {},
  "height": {},
  "created_at": "<string>",
  "NOT_FOUND": {},
  "UNAUTHORIZED": {}
}

​
Overview

Fetch metadata and details for a specific uploaded asset using its unique identifier.

​
Request

​
Path Parameters

​
assetId
string
required
The unique identifier of the asset (UUID format)

​
Headers

​
Authorization
string
required
Bearer token with your API key: Bearer sk-bab-your-api-key

​
Response

​
id
string
Unique identifier for the asset
​
name
string
Asset filename
​
url
string | null
S3 URL to access the asset
​
content_type
string
MIME type of the file
​
size
number | null
File size in bytes
​
state
string
Current state: uploading, processing, ready, or error
​
duration
number | null
Duration in seconds (for video/audio files)
​
width
number | null
Width in pixels (for image/video files)
​
height
number | null
Height in pixels (for image/video files)
​
created_at
string
ISO 8601 timestamp of when the asset was uploaded

​
Examples

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

​
Response Example

{
  "id": "ast_abc123xyz456789012",
  "name": "uploaded-file",
  "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"
}

​
Error Responses

​
NOT_FOUND
404
Asset not found or you don’t have access
{
  "error": "Asset not found",
  "code": "NOT_FOUND"
}
​
UNAUTHORIZED
401
Invalid or missing API key
{
  "error": "Unauthorized - Invalid API key",
  "code": "UNAUTHORIZED"
}

​
Use Cases

After uploading a large file, poll this endpoint to verify the upload completed successfully:
async function waitForAssetReady(assetId: string, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const asset = await getAsset(assetId);

    if (asset.state === 'ready') {
      return asset;
    }

    if (asset.state === 'failed') {
      throw new Error('Asset upload failed');
    }

    await new Promise(r => setTimeout(r, 2000)); // Wait 2s
  }

  throw new Error('Asset not ready after maximum attempts');
}
Before referencing an asset in your video project, verify it exists and is accessible:
async function validateAsset(assetId: string) {
  try {
    const asset = await getAsset(assetId);
    return asset.state === 'ready';
  } catch (error) {
    console.error('Asset validation failed:', error);
    return false;
  }
}
Retrieve the public URL to download or display the asset:
def get_asset_url(asset_id):
    asset = get_asset(asset_id)
    return asset['url']

# Use the URL to download
import requests
url = get_asset_url('ast_abc123xyz456789012')
content = requests.get(url).content

​
Next Steps

Upload Asset

Upload a new asset

List Assets

View all your assets