Lip Sync

Lip-sync jobs combine a source video and an audio track into a synchronized result video. The endpoint is asynchronous because video processing can take longer than a normal HTTP request.

Create Job

POST /api/open/v1/media/lip-sync/jobs
Authorization: Bearer KITTA_API_KEY
Content-Type: application/json

Request

{
  "video_url": "https://example.com/video.mp4",
  "audio_url": "https://example.com/audio.mp3"
}

Both URLs must be reachable by the API service. Use short-lived signed URLs for private media, and keep them valid long enough for the worker to download the files.

curl https://kittaai.com/api/open/v1/media/lip-sync/jobs \
  -H "Authorization: Bearer KITTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://example.com/video.mp4","audio_url":"https://example.com/audio.mp3"}'

Response

{
  "success": true,
  "message": "Job created",
  "data": {
    "id": "job_123",
    "status": "pending",
    "credits_used": 1100,
    "billing_duration_seconds": 11,
    "video_duration_seconds": 10.04,
    "audio_duration_seconds": 12.56,
    "billing_rule": "shorter_input_rounded_up"
  }
}

Persist the job id before updating user-visible state. If the browser closes, your backend should still be able to poll and attach the final result to the original project.

The service imports both remote files before creating or charging the lip-sync job. Import errors keep the standard code, message, and requestId fields and add safe recovery context:

{
  "code": "ERR_LIP_SYNC_MEDIA_DOWNLOAD_TIMEOUT",
  "message": "The lip-sync media download timed out. Please retry or use a faster, stable public URL.",
  "requestId": "req_123",
  "details": {
    "media_kind": "video",
    "stage": "download",
    "retryable": true
  }
}

Do not retry when retryable is false. A media import failure does not create a job or consume lip-sync credits.

List Jobs

GET /api/open/v1/media/lip-sync/jobs?page=1&limit=20&status=completed
Authorization: Bearer KITTA_API_KEY

Supported filters include page, limit, and status. Use listing for back-office recovery and project history, not as a high-frequency polling loop.

Get Job

GET /api/open/v1/media/lip-sync/jobs/{jobId}
Authorization: Bearer KITTA_API_KEY

Completed jobs include result metadata in data. Failed jobs include an error code or message. Keep terminal states immutable in your own database so repeated polling does not rewrite historical result records.

Billing And Credits

Video mode bills the shorter video/audio input, rounded up to a whole second. For example, a 10.04-second video with 12.56-second audio bills 11 seconds. Set video_extension: true only when the video should be extended and billed from audio duration. The create response is the final successful-job price; failed jobs receive a full refund.

If users can launch many jobs, enforce your own queue and concurrency limit. Use Profile to detect low balance before accepting expensive batches.

Video Dubbing: Generate Speech And Lip Sync From Text

The video dubbing endpoint combines TTS and lip sync in one create operation. The service generates audio with the selected voice and then automatically creates an asynchronous lip-sync job.

POST /api/open/v1/media/video-dubbing/jobs
Authorization: Bearer KITTA_API_KEY
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY
Content-Type: application/json

{
  "video_url": "https://example.com/video.mp4",
  "text": "Create speech and synchronized mouth movement for this video.",
  "reference_id": "YOUR_VOICE_ID",
  "model_id": "fishaudio-s21pro-flash",
  "speed": 1,
  "language": "en"
}

video_url, text, and reference_id are required. Use a unique Idempotency-Key for every new job and reuse the original value when retrying the same job after a timeout or network interruption.

Persist data.id from the create response as the jobId. TTS has completed when the create request returns, and the job is then in the lip-sync stage:

GET /api/open/v1/media/video-dubbing/jobs/{jobId}
Authorization: Bearer KITTA_API_KEY

The credits_used object reports tts, lip_sync, and total separately. If TTS succeeds but lip-sync creation fails, the completed TTS usage is not refunded; the error includes tts_audio_url and tts_credits_used, while any unsuccessful lip-sync reservation is not retained.

Errors