# Lipsync

## Generate lip sync from URLs

`client.lipsync.generate(LipsyncGenerateParamsbody, RequestOptionsoptions?): LipsyncGenerate`

**post** `/v1/lipsync/generate`

Starts a lip sync job from exactly one remote video URL and one remote audio URL.
The response includes a request identifier to poll later.

### Parameters

- `body: LipsyncGenerateParams`

  - `inputs: Array<Input>`

    Exactly one video input and one audio input (order does not matter).

    - `type: "video" | "audio"`

      Type of input media.

      - `"video"`

      - `"audio"`

    - `url: string`

      URL of the media resource.

  - `disable_active_speaker_detection?: boolean`

    Disable active speaker detection and use max-face lipsync preprocessing.

  - `reference_id?: string`

    Optional client-provided identifier for later retrieval.

### Returns

- `LipsyncGenerate`

  - `request_id: string`

    Identifier of the created lip sync request.

  - `status: "success"`

    Current state of the newly created request.

    - `"success"`

### Example

```typescript
import Chamelaion from 'chamelaion';

const client = new Chamelaion({
  apiKey: process.env['CHAMELAION_API_KEY'], // This is the default and can be omitted
});

const lipsyncGenerate = await client.lipsync.generate({
  inputs: [
    { type: 'video', url: 'https://cdn.example.com/episodes/42.mp4' },
    { type: 'audio', url: 'https://cdn.example.com/dubs/42-japanese.wav' },
  ],
  reference_id: 'dub-episode-42',
});

console.log(lipsyncGenerate.request_id);
```

#### Response

```json
{
  "status": "success",
  "request_id": "6f82a2d8-a6d4-4e8a-a0fa-e8b09823a2d8"
}
```

## Generate lip sync from uploaded media

`client.lipsync.generateWithMedia(LipsyncGenerateWithMediaParamsbody, RequestOptionsoptions?): LipsyncGenerate`

**post** `/v1/lipsync/generate-with-media`

Starts a lip sync job by uploading one video file and one audio file as multipart form-data.

### Parameters

- `body: LipsyncGenerateWithMediaParams`

  - `audio: Uploadable`

    Target audio file.

  - `video: Uploadable`

    Source video file.

  - `disable_active_speaker_detection?: boolean`

    Disable active speaker detection and use max-face lipsync preprocessing.

  - `model?: "lipsync-2"`

    Optional model selector.

    - `"lipsync-2"`

  - `reference_id?: string`

    Optional client-provided identifier for later retrieval.

### Returns

- `LipsyncGenerate`

  - `request_id: string`

    Identifier of the created lip sync request.

  - `status: "success"`

    Current state of the newly created request.

    - `"success"`

### Example

```typescript
import Chamelaion from 'chamelaion';

const client = new Chamelaion({
  apiKey: process.env['CHAMELAION_API_KEY'], // This is the default and can be omitted
});

const lipsyncGenerate = await client.lipsync.generateWithMedia({
  audio: fs.createReadStream('path/to/file'),
  video: fs.createReadStream('path/to/file'),
  model: 'lipsync-2',
  reference_id: 'upload-demo-01',
});

console.log(lipsyncGenerate.request_id);
```

#### Response

```json
{
  "status": "success",
  "request_id": "3b7df3e8-f578-44de-b4f5-5f58dd6b89e0"
}
```

## Domain Types

### Lipsync Generate

- `LipsyncGenerate`

  - `request_id: string`

    Identifier of the created lip sync request.

  - `status: "success"`

    Current state of the newly created request.

    - `"success"`

# Requests

## Get lip sync request

`client.lipsync.requests.retrieve(stringid, RequestOptionsoptions?): LipsyncRequest`

**get** `/v1/lipsync/requests/{id}`

Returns a single lip sync request by request UUID or `reference_id`.

### Parameters

- `id: string`

### Returns

- `LipsyncRequest`

  - `id: string`

    Lip sync request ID.

  - `created_at: string`

    Request creation time in UTC.

  - `status: string`

    Current request status.

  - `error_message?: string`

    Failure message when status is `failed`.

  - `finished_at?: string`

    Request processing completion time in UTC.

  - `output_url?: string`

    URL to the generated output media, when available.

  - `reference_id?: string`

    Client-provided identifier for this request.

  - `started_at?: string`

    Request processing start time in UTC.

### Example

```typescript
import Chamelaion from 'chamelaion';

const client = new Chamelaion({
  apiKey: process.env['CHAMELAION_API_KEY'], // This is the default and can be omitted
});

const lipsyncRequest = await client.lipsync.requests.retrieve(
  '6f82a2d8-a6d4-4e8a-a0fa-e8b09823a2d8',
);

console.log(lipsyncRequest.id);
```

#### Response

```json
{
  "id": "6f82a2d8-a6d4-4e8a-a0fa-e8b09823a2d8",
  "reference_id": "dub-episode-42",
  "status": "completed",
  "created_at": "2026-04-07T10:00:00Z",
  "started_at": "2026-04-07T10:00:05Z",
  "finished_at": "2026-04-07T10:01:30Z",
  "output_url": "https://storage.chamelaion.com/output/6f82a2d8.mp4"
}
```

## List lip sync requests

`client.lipsync.requests.list(RequestListParamsquery?, RequestOptionsoptions?): RequestListResponse`

**get** `/v1/lipsync/requests`

Returns a paginated list of lip sync requests for the authenticated account.

### Parameters

- `query: RequestListParams`

  - `limit?: number`

    Maximum number of items to return.

  - `offset?: number`

    Number of items to skip before returning results.

  - `reference_id?: string`

    Filter requests by exact `reference_id`.

### Returns

- `RequestListResponse`

  - `data: Array<LipsyncRequest>`

    - `id: string`

      Lip sync request ID.

    - `created_at: string`

      Request creation time in UTC.

    - `status: string`

      Current request status.

    - `error_message?: string`

      Failure message when status is `failed`.

    - `finished_at?: string`

      Request processing completion time in UTC.

    - `output_url?: string`

      URL to the generated output media, when available.

    - `reference_id?: string`

      Client-provided identifier for this request.

    - `started_at?: string`

      Request processing start time in UTC.

  - `pagination: Pagination`

    - `limit: number`

      Applied page size.

    - `offset: number`

      Applied result offset.

    - `total: number`

      Total number of matching records.

### Example

```typescript
import Chamelaion from 'chamelaion';

const client = new Chamelaion({
  apiKey: process.env['CHAMELAION_API_KEY'], // This is the default and can be omitted
});

const requests = await client.lipsync.requests.list();

console.log(requests.data);
```

#### Response

```json
{
  "data": [
    {
      "id": "6f82a2d8-a6d4-4e8a-a0fa-e8b09823a2d8",
      "reference_id": "batch-2026-04",
      "status": "completed",
      "created_at": "2026-03-30T11:00:00Z",
      "started_at": "2026-03-30T11:00:04Z",
      "finished_at": "2026-03-30T11:01:09Z",
      "output_url": "https://storage.chamelaion.com/output/6f82a2d8.mp4"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "reference_id": "batch-2026-04",
      "status": "queued",
      "created_at": "2026-03-30T11:02:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 2
  }
}
```

## Domain Types

### Lipsync Request

- `LipsyncRequest`

  - `id: string`

    Lip sync request ID.

  - `created_at: string`

    Request creation time in UTC.

  - `status: string`

    Current request status.

  - `error_message?: string`

    Failure message when status is `failed`.

  - `finished_at?: string`

    Request processing completion time in UTC.

  - `output_url?: string`

    URL to the generated output media, when available.

  - `reference_id?: string`

    Client-provided identifier for this request.

  - `started_at?: string`

    Request processing start time in UTC.