> ## 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 uses standard HTTP methods and status codes. Most endpoints return JSON; transcript exports can also return SRT or VTT.

For account settings, team management, media tools, and other workflows, use the [action catalog](https://api-docs.voicecheap.ai/docs/api-reference/actions.md). These workflows are also available through the [account MCP server](https://api-docs.voicecheap.ai/docs/ai/model-context-protocol.md), except webhook signing-secret creation and rotation, which require REST. Manage credentials in [Integrations](https://api-docs.voicecheap.ai/docs/ai/integrations.md) and check [usage limits](https://api-docs.voicecheap.ai/docs/api-reference/limits.md).

## Base URL

All API requests should be made to:

```text theme={null}
https://api.voicecheap.ai
```

## Authentication

Authenticate private REST calls with an API key in `x-api-key` or `Authorization: Bearer`. The OpenAPI document is public. See [Authentication](https://api-docs.voicecheap.ai/docs/authentication.md) for scoped credentials and OAuth for MCP.

## JSON action API

The account, team, project, voice and media-tool sections document each JSON action separately. These routes all use `POST`, including read and delete actions; send the arguments in the JSON body. The file-upload and existing project routes below retain their own HTTP methods.

Create an API key with `account:read`, set the `VOICECHEAP_API_KEY` environment variable, and try this read-only request:

```bash theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/account_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

A completed action returns HTTP 200 with its result in `data`. A long-running action returns HTTP 202 and a `requestId`; use [request status](https://api-docs.voicecheap.ai/docs/api-reference/actions/requests/action-request-get.md) to recover the result. A media job can continue after the action request completes.

Browse [all action pages by area](https://api-docs.voicecheap.ai/docs/api-reference/actions.md), or [discover the actions and schemas permitted for your key](https://api-docs.voicecheap.ai/docs/api-reference/discovery/actions-list.md). Each page lists its exact permissions, parameters, examples and errors.

## Content Types

* **Request**: Use `multipart/form-data` for file uploads, `application/json` for other requests
* **Response**: JSON endpoints return `application/json`. Transcript exports can also return SRT or VTT text.

## File uploads and existing project routes

> [card] [Transcribe Media](https://api-docs.voicecheap.ai/docs/api-reference/transcribe.md)
>
> `POST /v1/transcribe`
>
> Transcribe an uploaded file as JSON, SRT, or VTT.

> [card] [Export Project Transcript](https://api-docs.voicecheap.ai/docs/api-reference/project-transcript.md)
>
> `POST /v1/projects/{projectId}/transcript`
>
> Retrieve original or translated project transcripts.

> [card] [Create Project](https://api-docs.voicecheap.ai/docs/api-reference/create-project.md)
>
> `POST /v1/projects`
>
> Upload a video or audio file and start transcription without translation.

> [card] [Start Translation](https://api-docs.voicecheap.ai/docs/api-reference/translate.md)
>
> `POST /v1/translate`
>
> Upload a video or audio file and start a translation project.

> [card] [Dub Project](https://api-docs.voicecheap.ai/docs/api-reference/dub-project.md)
>
> `POST /v1/projects/{projectId}/dub`
>
> Dub an existing transcribed project from your translated SRT.

> [card] [Get Translation Status](https://api-docs.voicecheap.ai/docs/api-reference/translation-status.md)
>
> `GET /v1/translate/{projectId}/status`
>
> Check the status of a translation project and retrieve results.

> [card] [Get Project Details](https://api-docs.voicecheap.ai/docs/api-reference/project-details.md)
>
> `GET /v1/projects/{projectId}`
>
> Retrieve translated version history, lip-sync history, and project state.

> [card] [Delete Project](https://api-docs.voicecheap.ai/docs/api-reference/delete-project.md)
>
> `DELETE /v1/translate/{projectId}`
>
> Permanently delete a translation project and its assets.

## Translation Workflow

The typical workflow for translating a video is:

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

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

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

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

## Response Format

The existing file-upload and project routes below keep their endpoint-specific response formats.

Successful response fields depend on the endpoint. Project creation and dubbing start requests return `success`, `message` and `projectId`. Status and project-detail requests return project state; transcript requests return JSON, SRT or VTT. See the endpoint page for its exact response.

Errors return a JSON object with `code` and `message`, sometimes with `details`. See [Error Codes](https://api-docs.voicecheap.ai/docs/api-reference/errors.md).

## HTTP Status Codes

| Status Code | Description |
| - | - |
| 200 | Success |
| 201 | Created - A project or dubbing run was started |
| 202 | Accepted - Track the asynchronous action using its request identifier |
| 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 |
| 409 | Conflict - Project state does not allow the request |
| 413 | Payload Too Large - Uploaded file exceeds its limit |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
| 502 | Bad Gateway - Transcription could not complete |
| 503 | Service temporarily unavailable - Keep the same request identifier and inspect status before retrying |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.