> ## Documentation Index
> Fetch the complete documentation index at: https://tryunsora.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create voiceover
> Turn a script into natural speech with ElevenLabs Eleven v3 — pick from 20 voices and poll until the finished audio is ready.
Converts a script into natural speech using ElevenLabs Eleven v3. Credits are deducted when the job is queued. Poll [Poll voiceover status](/docs/api-reference/voiceovers/poll-status) with the returned `generation.id` until `status` is `COMPLETED` or `FAILED`.
Pick a voice first with [List voices](/docs/api-reference/voiceovers/voices) — every voice ships a preview clip so you can choose by ear.
## Headers
| Header | Required | Description |
| ----------------- | -------- | -------------------------------------------------------------------- |
| `Authorization` | Yes | `Bearer uns_live_*` API key or Clerk JWT |
| `Idempotency-Key` | No | Max 128 chars. Replays the same response for 24h on API key requests |
| `Content-Type` | Yes | `application/json` |
## Request body
Script to convert to speech. Max 10,000 characters. Use `<#x#>` between
words to insert a pause of `x` seconds (0.01–99.99), e.g. `Hello <#1.5#> world`.
Voice to use. One of: `Aria`, `Roger`, `Sarah`, `Laura`, `Charlie`, `George`,
`Callum`, `River`, `Liam`, `Charlotte`, `Alice`, `Matilda`, `Will`, `Jessica`,
`Eric`, `Chris`, `Brian`, `Daniel`, `Lily`, `Bill`.
See [List voices](/docs/api-reference/voiceovers/voices) for descriptions and preview clips of each voice.
`0`–`1`, default `0.5`. Higher values produce a more consistent delivery; lower values are more expressive.
`0`–`1`, default `1`. Controls how closely the output sticks to the base voice. Very high values can cause artifacts.
## Credits
6 credits per started 1,000 characters (a 2,300-character script costs 18 credits). Output is always `mp3`.
## Async completion
Poll [Poll voiceover status](/docs/api-reference/voiceovers/poll-status) with `generation.id` until `status` is `COMPLETED` or `FAILED`. Webhooks are not supported on the public API.
## Response
```json theme={null}
{
"success": true,
"generation": {
"id": "cm123abc",
"status": "QUEUED"
},
"creditsDeducted": 6,
"creditsRemaining": 94
}
```
## Example
```bash Basic theme={null} theme={null}
curl -X POST "https://mvp.tryunsora.com/api/v1/voiceovers/create" \
-H "Authorization: Bearer uns_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Welcome back to the channel. <#0.5#> Today we are breaking down the three biggest AI stories of the week.",
"voice_id": "George",
"stability": 0.5
}'
```
## Errors
| HTTP | When |
| ----- | --------------------------------------------------------- |
| `400` | Missing/invalid text, voice\_id, stability, or similarity |
| `401` | Invalid auth |
| `402` | Insufficient credits |
| `404` | User not found |
| `429` | Rate limit exceeded |
| `503` | Voiceover generation not configured |
| `500` | Server error |
## OpenAPI
````yaml POST /voiceovers/create
openapi: 3.1.0
info:
title: Unsora API
version: 1.2.0
description: >-
Public API for Unsora integrations. Use Bearer token from Clerk in
Authorization header.
servers:
- url: /api/v1
description: Versioned API
security: []
tags:
- name: User
- name: Connect
- name: Stripe
- name: Video
- name: Image
- name: Influencer
- name: Thumbnail
- name: Clipping
- name: Music
- name: Voiceover
- name: Uploads
paths:
/voiceovers/create:
post:
tags:
- Voiceover
summary: Create a script-to-voiceover job (ElevenLabs Eleven v3)
description: >-
Converts a script (max 10,000 chars) into natural speech using
ElevenLabs Eleven v3. Costs 6 credits per started 1,000 characters.
Output is always mp3. Poll /voiceovers/status/{id} for the result.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVoiceoverRequest'
responses:
'200':
description: Job queued
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVoiceoverResponse'
'402':
description: Insufficient credits
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: []
components:
schemas:
CreateVoiceoverRequest:
type: object
properties:
text:
type: string
maxLength: 10000
description: >-
Script to convert to speech (max 10,000 chars). Supports <#x#> tags
between words to pause for x seconds (0.01–99.99).
voice_id:
type: string
enum:
- Aria
- Roger
- Sarah
- Laura
- Charlie
- George
- Callum
- River
- Liam
- Charlotte
- Alice
- Matilda
- Will
- Jessica
- Eric
- Chris
- Brian
- Daniel
- Lily
- Bill
description: >-
Eleven v3 voice id — see GET /voiceovers/voices for descriptions and
preview clips
stability:
type: number
minimum: 0
maximum: 1
default: 0.5
description: Higher = more consistent delivery, lower = more expressive
similarity:
type: number
minimum: 0
maximum: 1
default: 1
description: How closely the output sticks to the base voice
required:
- text
- voice_id
CreateVoiceoverResponse:
type: object
properties:
success:
type: boolean
generation:
type: object
properties:
id:
type: string
status:
type: string
required:
- id
- status
creditsDeducted:
type: number
creditsRemaining:
type: number
required:
- success
- generation
- creditsDeducted
- creditsRemaining
ErrorResponse:
type: object
properties:
success:
type: boolean
error:
type: string
code:
type: string
message:
type: string
required:
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````