Skip to main content
POST
/
api
/
v1
/
assets
{
  "id": "<string>",
  "name": "<string>",
  "url": {},
  "content_type": "<string>",
  "size": {},
  "state": "<string>",
  "duration": {},
  "width": {},
  "height": {},
  "created_at": "<string>",
  "FILE_TOO_LARGE": {},
  "UPLOAD_FAILED": {},
  "VALIDATION_ERROR": {}
}

​
Overview

Upload assets (videos, images, audio files) to Babou’s cloud storage. Uploaded assets can be referenced in your video projects and used across multiple chapters.
Maximum file size: 100MB per upload

​
Request

​
Headers

​
Authorization
string
required
Bearer token with your API key: Bearer sk-bab-your-api-key
​
Content-Type
string
required
The MIME type of the file being uploaded (e.g., video/mp4, image/png, audio/mpeg)

​
Body

Send the raw binary file data as the request body.
​
(raw binary)
binary
required
The raw file content

​
Supported File Types

Video:
  • video/mp4
  • video/quicktime (.mov)
  • video/x-msvideo (.avi)
  • video/webm
Images:
  • image/png
  • image/jpeg
  • image/gif
  • image/webp
  • image/svg+xml
Audio:
  • audio/mpeg (.mp3)
  • audio/wav
  • audio/ogg
  • audio/aac

​
Response

​
id
string
Unique identifier for the uploaded asset
​
name
string
Asset filename
​
url
string | null
S3 URL to access the asset (null until upload completes)
​
content_type
string
MIME type of the uploaded file
​
size
number | null
File size in bytes
​
state
string
Upload state: uploading, processing, ready, or error
​
duration
number | null
Duration in seconds (for video/audio files, null for images)
​
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 upload

​
Examples

# Upload an image
curl -X POST https://api.babou.ai/api/v1/assets \
  -H "Authorization: Bearer $BABOU_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary "@/path/to/image.png"

# Upload a video
curl -X POST https://api.babou.ai/api/v1/assets \
  -H "Authorization: Bearer $BABOU_API_KEY" \
  -H "Content-Type: video/mp4" \
  --data-binary "@/path/to/video.mp4"

​
Response Example

{
  "id": "ast_abc123xyz456789012",
  "name": "uploaded-file",
  "url": "s3://babou-assets/assets/ast_abc123xyz456789012-original",
  "content_type": "image/png",
  "size": 245678,
  "state": "processing",
  "duration": null,
  "width": null,
  "height": null,
  "created_at": "2025-12-02T10:00:00Z"
}

​
Error Responses

​
FILE_TOO_LARGE
413
File exceeds 100MB limit
{
  "error": "File size exceeds maximum allowed size of 100MB",
  "code": "FILE_TOO_LARGE"
}
​
UPLOAD_FAILED
500
S3 upload failed
{
  "error": "Failed to upload file to storage",
  "code": "UPLOAD_FAILED"
}
​
VALIDATION_ERROR
400
Invalid or missing Content-Type header
{
  "error": "Content-Type header is required",
  "code": "VALIDATION_ERROR"
}

​
Best Practices

Validate that your file is under 100MB before making the request to avoid errors:
const stats = fs.statSync(filePath);
if (stats.size > 100 * 1024 * 1024) {
  throw new Error('File exceeds 100MB limit');
}
Save the returned id and url in your database to reference the asset later in your video projects.
Always set the correct Content-Type header matching your file format. This ensures proper processing and display.
Implement retry logic for failed uploads, especially for large files that may fail due to network issues.
async function uploadWithRetry(filePath: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await uploadAsset(filePath, 'video/mp4');
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, 1000 * (i + 1)));
    }
  }
}

​
Next Steps

Get Asset

Retrieve asset details by ID

List Assets

View all your uploaded assets

Asset Management Guide

Learn how to use assets in your videos