POST /aiworkflow

Create an AI dubbing (voiceover) for a video through the AI workflow endpoint. Dubbing is produced by the same /aiworkflow endpoint used for transcription and translation — the type field and a few flags decide what gets generated.

📘

Authorization

All requests require a valid Panda API token in the Authorization header (no Bearer prefix).

🚧

Dubbing depends on the video's subtitles

TRANSLATION and standalone DUBBING require a source subtitle in from_lang to already exist on the video. On a video that has no subtitle yet, both return 400 "You need to create a from_lang subtitle first".

To dub a video from scratch (audio only, no subtitle yet), use type: "TRANSCRIPTION" with generate_dubbing: true — it transcribes the audio first and then dubs, in a single request.

Choosing the workflow type

⚠️

Important: in the TRANSCRIPTION flow the dubbing/translation targets come from additional_langs, not from to_lang. generate_dubbing: true is what turns a transcription/translation into a dubbing — without it you only get subtitles. Whenever generate_dubbing is true, background_sound_mode is required.

HTTP Method & Path

POST /aiworkflow

Base URL: https://api-v2.pandavideo.com.br

Authentication Requirements

• Security Scheme: PandaAuth (apiKey)
• Header: Authorization: <your_api_token> (no Bearer prefix)

Parameters

Request Body

Content-Type: application/json

The body may be a single job object or an array of job objects (submit several jobs in one request). Unknown fields are rejected (additionalProperties: false).

Body Parameters (per item)

Example — dub from scratch (TRANSCRIPTION + dubbing)

Use this for a video that has no subtitle yet. It transcribes pt-BR and dubs into English and Spanish in one request.

[
  {
    "type": "TRANSCRIPTION",
    "video_id": "5a3b5516-b08f-4f94-8143-3e7e84fddd6b",
    "from_lang": "pt-BR",
    "generate_dubbing": true,
    "background_sound_mode": "ai",
    "tier": "essential",
    "num_speakers": 0,
    "clone_original_voice": true,
    "additional_langs": [
      { "lang": "en" },
      { "lang": "es" }
    ]
  }
]

Example — translate an existing subtitle and dub it (TRANSLATION)

Requires a from_lang subtitle already on the video.

[
  {
    "type": "TRANSLATION",
    "video_id": "5a3b5516-b08f-4f94-8143-3e7e84fddd6b",
    "from_lang": "pt-BR",
    "to_lang": "en",
    "generate_dubbing": true,
    "background_sound_mode": "ai",
    "tier": "essential",
    "clone_original_voice": true
  }
]

Example — dub an existing subtitle (DUBBING)

Requires a from_lang subtitle already on the video. No translation.

[
  {
    "type": "DUBBING",
    "video_id": "5a3b5516-b08f-4f94-8143-3e7e84fddd6b",
    "from_lang": "pt-BR",
    "background_sound_mode": "ai",
    "voice_id": "your_voice_id",
    "num_speakers": 0
  }
]

Response

Success Response (200)

The endpoint returns the accepted job with a generated id. Processing is asynchronous — track progress with the workflow listing endpoint. When you submit a single object the response is a single object; when you submit an array the response is an array (one item per accepted job).

{
  "id": "3048a34f-5d3a-4244-89d9-f9072ccc682a",
  "type": "TRANSCRIPTION",
  "video_id": "5a3b5516-b08f-4f94-8143-3e7e84fddd6b",
  "from_lang": "pt-BR",
  "generate_dubbing": true,
  "background_sound_mode": "ai",
  "tier": "essential",
  "additional_langs": [
    { "lang": "en" },
    { "lang": "es" }
  ]
}

Response Schema

⚠️

Important: the dubbing and translation sub-jobs (one per additional_langs entry) are created and processed asynchronously. Poll the workflow listing endpoint to follow their status.

Error Responses

• 400 Bad Request — validation error. Common cases:
  • "You need to create a from_lang subtitle first" — TRANSLATION/DUBBING on a video without the source subtitle.
  • "You need to delete the to_lang subtitle first" — the target subtitle already exists.
  • "Subtitles already exist for this lang, please delete them first" — transcription for a language that already has a subtitle.
  • "background_sound_mode is required when generate_dubbing is true".
  • "tier is required for TRANSCRIPTION" / "... for TRANSLATION" (when generate_dubbing is false).
  • "Lipsync is not supported for videos longer than 60 minutes".
  • "There is already a dubbing/translation/transcription in progress for this video".
  • "Not enough credits".
• 404 Not Found — source video not found.
• 500 Internal Server Error — server-side error.

Example Usage

cURL

curl -X POST \
  'https://api-v2.pandavideo.com.br/aiworkflow' \
  -H 'Authorization: your_api_token_here' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "type": "TRANSCRIPTION",
    "video_id": "5a3b5516-b08f-4f94-8143-3e7e84fddd6b",
    "from_lang": "pt-BR",
    "generate_dubbing": true,
    "background_sound_mode": "ai",
    "tier": "essential",
    "num_speakers": 0,
    "clone_original_voice": true,
    "additional_langs": [
      { "lang": "en" },
      { "lang": "es" }
    ]
  }
]'