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

# API Reference

> Complete reference for the VoiceCheap REST API

# API Reference

The VoiceCheap API is organized around REST principles. It uses standard HTTP methods, returns JSON-encoded responses, and uses standard HTTP response codes.

## Base URL

All API requests should be made to:

```
https://api.voicecheap.ai
```

## Authentication

All requests require an API key passed in the `x-api-key` header. See the [Authentication](/docs/authentication) page for details.

## Content Types

* **Request**: Use `multipart/form-data` for file uploads, `application/json` for other requests
* **Response**: All responses are returned as `application/json`

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Start Translation" icon="play" href="/docs/api-reference/translate">
    `POST /v1/translate`

    Upload a video or audio file and start a translation project.
  </Card>

  <Card title="Get Translation Status" icon="magnifying-glass" href="/docs/api-reference/translation-status">
    `GET /v1/translate/{projectId}/status`

    Check the status of a translation project and retrieve results.
  </Card>

  <Card title="Get Project Details" icon="list-tree" href="/docs/api-reference/project-details">
    `GET /v1/projects/{projectId}`

    Retrieve translated version history, lip-sync history, and project state.
  </Card>

  <Card title="Delete Project" icon="trash" href="/docs/api-reference/delete-project">
    `DELETE /v1/translate/{projectId}`

    Permanently delete a translation project and its assets.
  </Card>
</CardGroup>

## Translation Workflow

The typical workflow for translating a video is:

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Processing

    Client->>API: POST /v1/translate (file + options)
    API->>Processing: Queue translation job
    API-->>Client: 200 OK (projectId)

    loop Poll for status
        Client->>API: GET /v1/translate/{projectId}/status
        API-->>Client: Status (processing/success/failed)
    end

    Note over Client: Download translated video URL when status is "success"
```

## Response Format

All successful responses follow this general structure:

```json theme={null}
{
  "success": true,
  "message": "Description of the result"
  // Additional fields specific to the endpoint
}
```

Error responses follow this structure:

```json theme={null}
{
  "code": "ERROR_CODE",
  "message": "Human-readable error description"
}
```

## HTTP Status Codes

| Status Code | Description                                     |
| ----------- | ----------------------------------------------- |
| 200         | Success                                         |
| 400         | Bad Request - Invalid parameters                |
| 401         | Unauthorized - Invalid or missing API key       |
| 403         | Forbidden - Insufficient permissions or credits |
| 404         | Not Found - Resource doesn't exist              |
| 429         | Too Many Requests - Rate limit exceeded         |
| 500         | Internal Server Error                           |