> ## Documentation Index
> Fetch the complete documentation index at: https://docs.babou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Introduction to the Babou REST API

The Babou REST API lets you create, manage, and export video projects programmatically. No rendering expertise required - just straightforward REST calls.

## Base URL

All API requests should be made to:

```
https://api.babou.ai/api/v1
```

## Authentication

Every API request must include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer sk-bab-your-api-key-here
```

See the [Authentication guide](/authentication) for detailed information.

## API Structure

The Babou API is organized around creating and managing video projects:

<Steps>
  <Step title="Projects">
    Create a project container for your video
  </Step>

  <Step title="Chapters">
    Add one or more chapters to organize your video content
  </Step>

  <Step title="Prompts">
    Submit text prompts to create video content for each chapter
  </Step>

  <Step title="Exports">
    Export your complete project as a downloadable video file
  </Step>
</Steps>

## Core Concepts

### Projects

A **project** is the top-level container for a video. It holds metadata like name and description, and contains one or more chapters.

```json theme={null}
{
  "id": "prj_abc123xyz",
  "name": "My Marketing Video",
  "description": "Q4 2025 product launch",
  "created_at": "2025-12-02T10:00:00Z"
}
```

### Chapters

A **chapter** is a segment of your video. Each chapter can have its own content, duration, and video prompt. Chapters are rendered sequentially to create the final video.

```json theme={null}
{
  "id": "cht_def456uvw",
  "project_id": "prj_abc123xyz",
  "name": "Introduction",
  "duration": 30,
  "created_at": "2025-12-02T10:01:00Z"
}
```

### Prompts

A **prompt** is a text description submitted to create video content for a chapter. Babou's AI processes the prompt and creates video content automatically.

```json theme={null}
{
  "prompt_id": "int_abc123xyz789",
  "status": "processing",
  "message": "Prompt processing started",
  "estimated_time": "30-90 seconds"
}
```

### Assets

**Assets** are media files (videos, images, audio) you upload to use in your projects. Upload assets separately, then reference them in your prompts.

```json theme={null}
{
  "id": "ast_abc123xyz456789012",
  "url": "https://babou-assets.s3.amazonaws.com/assets/...",
  "content_type": "image/png",
  "state": "ready"
}
```

## API Endpoints

### Assets

<CardGroup cols={2}>
  <Card title="Upload Asset" icon="upload" href="/api-reference/assets/upload">
    `POST /api/v1/assets`
  </Card>

  <Card title="Get Asset" icon="download" href="/api-reference/assets/get">
    `GET /api/v1/assets/{assetId}`
  </Card>

  <Card title="List Assets" icon="list" href="/api-reference/assets/list">
    `GET /api/v1/assets`
  </Card>
</CardGroup>

### Projects

<CardGroup cols={2}>
  <Card title="Create Project" icon="plus" href="/api-reference/projects/create">
    `POST /api/v1/projects`
  </Card>

  <Card title="List Projects" icon="list" href="/api-reference/projects/list">
    `GET /api/v1/projects`
  </Card>

  <Card title="Get Project" icon="eye" href="/api-reference/projects/get">
    `GET /api/v1/projects/{projectId}`
  </Card>
</CardGroup>

### Chapters

<CardGroup cols={2}>
  <Card title="Create Chapter" icon="plus" href="/api-reference/chapters/create">
    `POST /api/v1/projects/{projectId}/chapters`
  </Card>

  <Card title="List Chapters" icon="list" href="/api-reference/chapters/list">
    `GET /api/v1/projects/{projectId}/chapters`
  </Card>

  <Card title="Get Chapter" icon="eye" href="/api-reference/chapters/get">
    `GET /api/v1/projects/{projectId}/chapters/{chapterId}`
  </Card>
</CardGroup>

### Prompts

<CardGroup cols={1}>
  <Card title="Submit Prompt" icon="wand-magic-sparkles" href="/api-reference/prompts/submit">
    `POST /api/v1/projects/{projectId}/chapters/{chapterId}/prompt`
  </Card>
</CardGroup>

### Exports

<CardGroup cols={2}>
  <Card title="Start Export" icon="file-export" href="/api-reference/exports/start">
    `POST /api/v1/projects/{projectId}/export`
  </Card>

  <Card title="Get Export Status" icon="circle-check" href="/api-reference/exports/status">
    `GET /api/v1/projects/{projectId}/export`
  </Card>
</CardGroup>

## Rate Limiting

The Babou API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per API key.

<Info>
  If you exceed rate limits, you'll receive a `429 Too Many Requests` response. Implement exponential backoff in your retry logic.
</Info>

## Request Format

All POST and PUT requests should send JSON in the request body with the `Content-Type: application/json` header (except for asset uploads, which send binary data).

```bash theme={null}
curl -X POST https://api.babou.ai/api/v1/projects \
  -H "Authorization: Bearer $BABOU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project"}'
```

## Response Format

All API responses are JSON. Successful responses return the relevant data:

```json theme={null}
{
  "id": "prj_abc123xyz",
  "name": "My Project",
  "created_at": "2025-12-02T10:00:00Z"
}
```

Error responses include an `error` message and a `code`:

```json theme={null}
{
  "error": "Project not found",
  "code": "NOT_FOUND"
}
```

See the [Error Reference](/api-reference/errors) for complete error documentation.

## ID Formats

Babou uses predictable ID prefixes to make debugging easier:

* **Projects**: `prj_[A-Za-z0-9]{21}` (e.g., `prj_abc123xyz`)
* **Chapters**: `cht_[A-Za-z0-9]{21}` (e.g., `cht_def456uvw`)
* **Prompts/Interactions**: `int_[A-Za-z0-9]{21}` (e.g., `int_abc123xyz789`)
* **Exports**: `exp_[A-Za-z0-9]{21}` (e.g., `exp_xyz789abc123`)
* **Assets**: `ast_[A-Za-z0-9]{21}` (e.g., `ast_abc123xyz456`)

## Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

```
2025-12-02T10:00:00Z
```

## Pagination

List endpoints support pagination via `limit` and `offset` parameters:

```bash theme={null}
GET /api/v1/projects?limit=20&offset=40
```

Response includes pagination metadata:

```json theme={null}
{
  "projects": [...],
  "pagination": {
    "limit": 20,
    "offset": 40,
    "total": 150
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first video in 5 minutes
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn how to authenticate requests
  </Card>

  <Card title="Error Reference" icon="triangle-exclamation" href="/api-reference/errors">
    Understand error codes and responses
  </Card>

  <Card title="Video Creation Guide" icon="video" href="/guides/video-creation-workflow">
    Deep dive into creating videos
  </Card>
</CardGroup>