# Lipsync ## Generate lip sync from URLs `lipsync.generate(LipsyncGenerateParams**kwargs) -> 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 - `inputs: Iterable[Input]` Exactly one video input and one audio input (order does not matter). - `type: Literal["video", "audio"]` Type of input media. - `"video"` - `"audio"` - `url: str` URL of the media resource. - `disable_active_speaker_detection: Optional[bool]` Disable active speaker detection and use max-face lipsync preprocessing. - `reference_id: Optional[str]` Optional client-provided identifier for later retrieval. ### Returns - `class LipsyncGenerate: …` - `request_id: str` Identifier of the created lip sync request. - `status: Literal["success"]` Current state of the newly created request. - `"success"` ### Example ```python import os from chamelaion import Chamelaion client = Chamelaion( api_key=os.environ.get("CHAMELAION_API_KEY"), # This is the default and can be omitted ) lipsync_generate = 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", }], disable_active_speaker_detection=False, reference_id="dub-episode-42", ) print(lipsync_generate.request_id) ``` #### Response ```json { "status": "success", "request_id": "6f82a2d8-a6d4-4e8a-a0fa-e8b09823a2d8" } ``` ## Generate lip sync from uploaded media `lipsync.generate_with_media(LipsyncGenerateWithMediaParams**kwargs) -> 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 - `audio: FileTypes` Target audio file. - `video: FileTypes` Source video file. - `disable_active_speaker_detection: Optional[bool]` Disable active speaker detection and use max-face lipsync preprocessing. - `model: Optional[Literal["lipsync-2"]]` Optional model selector. - `"lipsync-2"` - `reference_id: Optional[str]` Optional client-provided identifier for later retrieval. ### Returns - `class LipsyncGenerate: …` - `request_id: str` Identifier of the created lip sync request. - `status: Literal["success"]` Current state of the newly created request. - `"success"` ### Example ```python import os from chamelaion import Chamelaion client = Chamelaion( api_key=os.environ.get("CHAMELAION_API_KEY"), # This is the default and can be omitted ) lipsync_generate = client.lipsync.generate_with_media( audio=b"(binary)", video=b"(binary)", disable_active_speaker_detection=False, model="lipsync-2", reference_id="upload-demo-01", ) print(lipsync_generate.request_id) ``` #### Response ```json { "status": "success", "request_id": "3b7df3e8-f578-44de-b4f5-5f58dd6b89e0" } ``` ## Domain Types ### Lipsync Generate - `class LipsyncGenerate: …` - `request_id: str` Identifier of the created lip sync request. - `status: Literal["success"]` Current state of the newly created request. - `"success"` # Requests ## Get lip sync request `lipsync.requests.retrieve(strid) -> LipsyncRequest` **get** `/v1/lipsync/requests/{id}` Returns a single lip sync request by request UUID or `reference_id`. ### Parameters - `id: str` ### Returns - `class LipsyncRequest: …` - `id: str` Lip sync request ID. - `created_at: datetime` Request creation time in UTC. - `status: str` Current request status. - `error_message: Optional[str]` Failure message when status is `failed`. - `finished_at: Optional[datetime]` Request processing completion time in UTC. - `output_url: Optional[str]` URL to the generated output media, when available. - `reference_id: Optional[str]` Client-provided identifier for this request. - `started_at: Optional[datetime]` Request processing start time in UTC. ### Example ```python import os from chamelaion import Chamelaion client = Chamelaion( api_key=os.environ.get("CHAMELAION_API_KEY"), # This is the default and can be omitted ) lipsync_request = client.lipsync.requests.retrieve( "6f82a2d8-a6d4-4e8a-a0fa-e8b09823a2d8", ) print(lipsync_request.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 `lipsync.requests.list(RequestListParams**kwargs) -> RequestListResponse` **get** `/v1/lipsync/requests` Returns a paginated list of lip sync requests for the authenticated account. ### Parameters - `limit: Optional[int]` Maximum number of items to return. - `offset: Optional[int]` Number of items to skip before returning results. - `reference_id: Optional[str]` Filter requests by exact `reference_id`. ### Returns - `class RequestListResponse: …` - `data: List[LipsyncRequest]` - `id: str` Lip sync request ID. - `created_at: datetime` Request creation time in UTC. - `status: str` Current request status. - `error_message: Optional[str]` Failure message when status is `failed`. - `finished_at: Optional[datetime]` Request processing completion time in UTC. - `output_url: Optional[str]` URL to the generated output media, when available. - `reference_id: Optional[str]` Client-provided identifier for this request. - `started_at: Optional[datetime]` Request processing start time in UTC. - `pagination: Pagination` - `limit: int` Applied page size. - `offset: int` Applied result offset. - `total: int` Total number of matching records. ### Example ```python import os from chamelaion import Chamelaion client = Chamelaion( api_key=os.environ.get("CHAMELAION_API_KEY"), # This is the default and can be omitted ) requests = client.lipsync.requests.list() print(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 - `class LipsyncRequest: …` - `id: str` Lip sync request ID. - `created_at: datetime` Request creation time in UTC. - `status: str` Current request status. - `error_message: Optional[str]` Failure message when status is `failed`. - `finished_at: Optional[datetime]` Request processing completion time in UTC. - `output_url: Optional[str]` URL to the generated output media, when available. - `reference_id: Optional[str]` Client-provided identifier for this request. - `started_at: Optional[datetime]` Request processing start time in UTC.