# Generate

This method holds the main functionality of the SYNC.AI API allowing users to create animation curves stored in FBX or CSV to integrate into other tools. 

This endpoint comes in two flavors, a JSON API and a Multipart Form based API. The JSON API is for when no audio is provided and instead a Text-to-Speech (TTS) engine is used to generate the audio. The Multipart Form based API is for instances when you have an audio file already to generate animation content for.

Given the asynchronous nature of the API we provide web-hooks for when a request leaves the queue and starts being processed, if it fails to be processed, and when it finishes processing successfully. They also contain a job ID which is a UUID Emotech employees can use to find logs and diagnose any issues you find. Advanced users who are able to write and deploy a service to handle these web-hook requests may want to make use of these to optimize their own content generation pipelines. Other users can ignore these details.

The JSON and Multipart APIs both require the same json object sent to them referred to as the "Job Specification JSON Object". Refer to the section after the API tables for a description of this object.

## Generate animation output as in FBX or CSV file format.

<mark style="color:green;">`POST`</mark> `https://lipsync-ai.api.emotechlab.com/lipsync/generate`

#### Query Parameters

| Name                                    | Type   | Description                                                             |
| --------------------------------------- | ------ | ----------------------------------------------------------------------- |
| token<mark style="color:red;">\*</mark> | String | Your user token tied to your account is used to validate your identity. |

#### Headers

| Name                                           | Type | Description      |
| ---------------------------------------------- | ---- | ---------------- |
| content-type<mark style="color:red;">\*</mark> |      | application/json |

#### Request Body

| Name                                  | Type | Description                       |
| ------------------------------------- | ---- | --------------------------------- |
| job<mark style="color:red;">\*</mark> |      | The Job specification JSON Object |

{% tabs %}
{% tab title="200: OK OK" %}
Returns a UUID for the rendering job to allow the client to check its status in future. It also returns the job status which will currently always be queued.

```javascript
{
    "id":"314fb342-e7c0-474b-aab2-994d155f2062",
    "status":"queued"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid data" %}
Invalid job specification json - job specification json didn't match expected format.
{% endtab %}

{% tab title="401: Unauthorized Token is missing" %}
Token is missing. User didn’t include token when sending request to API.
{% endtab %}

{% tab title="401: Unauthorized Invalid token" %}
Token is not valid. Users used a token we can’t recognise.
{% endtab %}

{% tab title="403: Forbidden Token expired" %}
Token has expired. Please renew your subscription plan by logging into the portal.
{% endtab %}

{% tab title="403: Forbidden Token reached limits" %}
Token has reached request limit. Token has reached the request limit of your subscription plan. Please upgrade your plan if you require extra usage this month.
{% endtab %}

{% tab title="400: Bad Request Invalid request" %}
A valid job specification must be provided in a part named job. When using the multipart API a job json was not submitted.
{% endtab %}

{% tab title="400: Bad Request Corupt data" %}
Error when reading job specification - an error was encountered reading the form part. This likely means the part was malformed in some form.
{% endtab %}
{% endtabs %}

## Generate animation output as in FBX or CSV file format (Multipart).

<mark style="color:green;">`POST`</mark> `https://lipsync-ai.api.emotechlab.com/lipsync/generate`

#### Query Parameters

| Name                                    | Type   | Description                                                             |
| --------------------------------------- | ------ | ----------------------------------------------------------------------- |
| token<mark style="color:red;">\*</mark> | String | Your user token tied to your account is used to validate your identity. |

#### Headers

| Name                                           | Type | Description         |
| ---------------------------------------------- | ---- | ------------------- |
| content-type<mark style="color:red;">\*</mark> |      | multipart/form-data |

#### Request Body

| Name                                    | Type   | Description                                    |
| --------------------------------------- | ------ | ---------------------------------------------- |
| job<mark style="color:red;">\*</mark>   | Object | The Job specification JSON Object              |
| audio<mark style="color:red;">\*</mark> | Bytes  | An audio file containing the speech to animate |

{% tabs %}
{% tab title="200: OK OK" %}
Returns a UUID for the rendering job to allow the client to check its status in future. It also returns the job status which will currently always be queued.

```javascript
{
    "id":"314fb342-e7c0-474b-aab2-994d155f2062",
    "status":"queued"
}
```

{% endtab %}

{% tab title="401: Unauthorized Token is missing" %}
Token is missing. User didn’t include token when sending request to API.
{% endtab %}

{% tab title="401: Unauthorized Invalid token" %}
Token is not valid. Users used a token we can’t recognise.
{% endtab %}

{% tab title="403: Forbidden Token expired" %}
Token has expired. Please renew your subscription plan by logging into the portal.
{% endtab %}

{% tab title="403: Forbidden Token reached limits" %}
Token has reached request limit. Token has reached the request limit of your subscription plan. Please upgrade your plan if you require extra usage this month.
{% endtab %}

{% tab title="400: Bad Request Invalid data" %}
Invalid job specification json - job specification json didn't match expected format.
{% endtab %}

{% tab title="400: Bad Request Corupt data" %}
Error when reading job specification - an error was encountered reading the form part. This likely means the part was malformed in some form.
{% endtab %}

{% tab title="400: Bad Request Invalid request" %}
A valid job specification must be provided in a part named job. When using the multipart API a job json was not submitted.
{% endtab %}
{% endtabs %}

### Job Specification JSON

<table><thead><tr><th width="151">Field</th><th width="105">Type</th><th width="351">Description</th><th width="142">Required?</th></tr></thead><tbody><tr><td>target_rig</td><td>String</td><td>Target rig, specifies which rig we want. For FBX output we currently only accept "arkit". To generate a csv for your MetaHuman character, the value here should be "metahumans". </td><td>Yes</td></tr><tr><td>audio_url</td><td>String</td><td>Either a HTTP, S3 or OBS URL that points to an audio file to be downloaded by the engine.</td><td>No</td></tr><tr><td>tts_params</td><td>TTS Param Object</td><td>If no audio is provided, use this to specify which TTS engine and what parameters will be used. Otherwise default settings for the specified actor will be used instead.</td><td>No</td></tr><tr><td>text</td><td>String</td><td>A transcript of what the character will say. This service does not offer a translation API so this should match the language selected with the language parameter.</td><td>Yes</td></tr><tr><td>language</td><td>String</td><td>Language code - see section <a href="/pages/LmWIAOYIvoGKcegn2II0#language-codes">Language Codes</a> for information on supported codes and format.</td><td>Yes</td></tr><tr><td>actor</td><td>String</td><td>Voice for the TTS output if desired. Only required if no audio file is provided. Options are 'male' or 'female'.</td><td>No</td></tr><tr><td>emotion</td><td>Object</td><td>Emotion object. Controls the emotion expression on the actor's face.</td><td>No</td></tr><tr><td>output</td><td>Output Object</td><td>Set to fbx or csv object.</td><td>No</td></tr><tr><td>web_hooks</td><td>Object</td><td>Object with keys of the format “on_*” and webhook location URL values. POST requests are made with relevant information. Currently only used for offline/video rendering, including standalone animation jobs.</td><td>No</td></tr></tbody></table>

### Objects

#### TTS Object

<table><thead><tr><th width="156">Field</th><th width="96">Type</th><th width="346">Description</th><th>Required?</th></tr></thead><tbody><tr><td>engine</td><td>String</td><td>Name of the engine to use. Currently the only option is "Google".</td><td>Yes</td></tr><tr><td>speed</td><td>Number</td><td>Speed of the speech, 1.0 is 100% speed which is the normal speed.</td><td>No</td></tr><tr><td>voice</td><td>String</td><td>This is the name voice to use with Google’s TTS. Please consult their API documentation for speakers for the requested language. Otherwise an appropriate voice will be picked.</td><td>No</td></tr></tbody></table>

#### Emotion Object

<table><thead><tr><th width="154">Field</th><th width="100">Type</th><th width="344">Description</th><th>Required?</th></tr></thead><tbody><tr><td>expression</td><td>String</td><td>Can be one of: “neutral”, “happy”, “sad”, “surprise”, “fear”, “disappointed”.</td><td>No</td></tr><tr><td>level</td><td>Float</td><td>0.0 for no expression on the actor’s face, 1.0 for maximum expression.</td><td>No</td></tr></tbody></table>

#### Output Object

<table><thead><tr><th width="149">Field</th><th width="98">Type</th><th width="344">Description</th><th>Required?</th></tr></thead><tbody><tr><td>type</td><td>String</td><td>"csv" for a csv file or “fbx” for an fbx file.</td><td>Yes</td></tr></tbody></table>

#### Webhooks Object

<table><thead><tr><th width="148">Field</th><th width="93">Type</th><th width="354">Description </th><th>Required?</th></tr></thead><tbody><tr><td>on_success</td><td>String</td><td>A request is made to this URL when an offline job result is successfully uploaded to the provided URL.</td><td>No</td></tr><tr><td>on_fail</td><td>String</td><td>A request is made to this URL when an offline job fails.</td><td>No</td></tr><tr><td>on_running</td><td>String</td><td>A request is made to this URL when an offline job leaves the job queue and starts being processed.</td><td>No</td></tr></tbody></table>

*See* [*Webhooks section*](/sync.ai-api-documentation-animation/reference/sync.ai-api-overview/generate/webhooks.md) *for specifications.*

#### *Example JSON Request*

```
{
    "target_rig": "arkit",
    "text": "what the character is saying",
    "language": "en-US",
    "actor": “female”,
    "tts_params": { "engine": "Google"},
    "output": {"type": "fbx"},
    "emotion": {"expression": "happy", "level": 1.0}
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://emotech.gitbook.io/sync.ai-api-documentation-animation/reference/sync.ai-api-overview/generate.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.