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

# Speech, Talking Avatar, and Lip Sync

> Generate speech or animate an image or video using existing audio or a quoted voice script.

Use [API key authentication](/api-reference/authentication) for all operations
on this page. These mutations return `Content!`; use
[tasks and results](/api-reference/tasks-and-results) to follow their output.

## Text to speech

```graphql TextToSpeech theme={null}
mutation TextToSpeech($metadata: SimpleText2SpeechContentMetadata!) {
  textSpeechSimplify(metadata: $metadata) {
    id
    task { id status progress { finishCode } }
  }
}
```

```json Variables theme={null}
{
  "metadata": {
    "prompt": "Welcome to the studio.",
    "voiceModelId": "<VOICE_MODEL_ID>"
  }
}
```

`prompt: String!` supplies the speech and `voiceModelId: String!` selects a ready
voice model. Optional `emotion: Text2SpeechEmotion` and `speed: Text2SpeechSpeed`
use enums; this `speed` is different from the numeric `voiceSpeed` used below.

## Talking Avatar with existing audio

Animate a source image with an accessible audio media reference:

```graphql TalkingAvatar theme={null}
mutation TalkingAvatar($metadata: SimpleAudio2VideoContentMetadata!) {
  talkingAvatarAudioVideoSimplify(metadata: $metadata) {
    id
    task { id status progress { finishCode } }
  }
}
```

```json Variables theme={null}
{
  "metadata": {
    "modelId": "<IMAGE_MODEL_ID>",
    "srcImageMediaId": "<IMAGE_MEDIA_ID>",
    "srcAudioMediaId": "<AUDIO_MEDIA_ID>",
    "outputQuality": "best"
  }
}
```

## Lip Sync with existing audio

Provide a video source and the audio to synchronize:

```graphql LipSync theme={null}
mutation LipSync($metadata: SimpleAudio2VideoContentMetadata!) {
  videoLipSyncSimplify(metadata: $metadata) {
    id
    task { id status progress { finishCode } }
  }
}
```

```json Variables theme={null}
{
  "metadata": {
    "modelId": "<IMAGE_MODEL_ID>",
    "srcVideoMediaId": "<VIDEO_MEDIA_ID>",
    "srcAudioMediaId": "<AUDIO_MEDIA_ID>"
  }
}
```

## Use a script instead of existing audio

Talking Avatar and Lip Sync support script synthesis with a selected voice.
Request a duration quote for the exact script and speed before submission:

```graphql QuoteAvatarScript theme={null}
query QuoteAvatarScript($script: String!, $voiceSpeed: Float) {
  calculateTalkingAvatarScriptCredit(script: $script, voiceSpeed: $voiceSpeed) {
    id
    estimatedAudioDurationMs
    expiresAt
  }
}
```

```json Variables theme={null}
{
  "script": "Welcome to the studio.",
  "voiceSpeed": 1.0
}
```

Submit the avatar or lip-sync mutation with the same script and speed, a ready
voice model, and the returned `id` as `voiceScriptQuoteId`. Omit existing-audio inputs when choosing
script synthesis. For example, the variables for `TalkingAvatar` become:

```json TalkingAvatar variables theme={null}
{
  "metadata": {
    "modelId": "<IMAGE_MODEL_ID>",
    "srcImageMediaId": "<IMAGE_MEDIA_ID>",
    "voiceModelId": "<VOICE_MODEL_ID>",
    "voiceScript": "Welcome to the studio.",
    "voiceSpeed": 1.0,
    "voiceScriptQuoteId": "<QUOTE_ID>",
    "outputQuality": "best"
  }
}
```

The quote estimates speech duration; it is not generation completion or a
payment receipt. If the script or speed changes or the quote expires, obtain a
matching quote. When `voiceScriptQuoteId` is omitted, the generation flow
calculates a quote during submission.

## Shared avatar and lip-sync metadata

Both operations use `SimpleAudio2VideoContentMetadata`:

| Field | Type | Meaning |
| - | - | - |
| `modelId` | `String!` | Required ready image model. |
| `srcImageMediaId` | `ID` | Existing image for Talking Avatar. |
| `srcVideoMediaId` | `ID` | Existing video for Lip Sync. |
| `srcAudioMediaId` | `ID` | Existing audio input. |
| `inputImage`, `inputVideo`, `inputAudio` | Uploaded file inputs | Alternatives for integrations that provide verified file references. |
| `remixImage`, `remixVideo`, `remixAudio` | Remix file inputs | Alternative source references. |
| `voiceModelId` | `ID` | Required for script synthesis. |
| `voiceScript` | `String` | Script synthesis input for these two workflows. |
| `voiceScriptQuoteId` | `ID` | Optional existing quote for the exact script, speed, and account. Must still be valid when supplied. |
| `voiceSpeed` | `Float` | Script speed multiplier, `0.5` to `2.0`, default `1.0`. |
| `emotion` | `Text2SpeechEmotion` | Optional overall synthesis emotion. |
| `inputPrompt` | `String` | Optional style instructions. |
| `promptModifierIds` | `[ID!]` | Supported prompt modifiers. |
| `outputQuality` | `OutputQuality` | Quality supported by the chosen operation. Talking Avatar defaults to `best` when omitted. |
| `resolution` | `VideoResolution` | Target resolution where supported. |

Ordinary [image to video](/api-reference/image-to-video) and
[Extend](/api-reference/extend-video) place dialogue in prompt text. Their input
contracts differ from the script synthesis contract on this page.


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