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 FISHSPEECH_API_KEY
Content-Type: application/json

Request

{
  "videoUrl": "https://example.com/video.mp4",
  "audioUrl": "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://fishaudio.org/api/open/v1/media/lip-sync/jobs \
  -H "Authorization: Bearer FISHSPEECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoUrl":"https://example.com/video.mp4","audioUrl":"https://example.com/audio.mp3"}'

Response

{
  "success": true,
  "message": "Job created",
  "data": {
    "id": "job_123",
    "status": "queued"
  }
}

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.

List Jobs

GET /api/open/v1/media/lip-sync/jobs?page=1&limit=20&status=completed
Authorization: Bearer FISHSPEECH_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 FISHSPEECH_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

Lip-sync work usually charges by accepted job or completed processing duration. Validate video length and audio length before submission, and avoid automatically creating a second job when a poll request times out.

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

Errors