# Como criar legendas SRT de um vídeo com uma API > Envie o vídeo para POST /transcribe com output_format definido como srt e word_timestamps como false, espere o processamento terminar e salve o texto que voltar em um arquivo .srt. Se quiser a legenda traduzida para outro idioma, basta incluir o parâmetro translate_to. Aqui você vê como montar a requisição exata, o que vem dentro do SRT, como usar os tempos das palavras para quebrar as linhas direitinho, como converter para WebVTT e como colocar a legenda no vídeo. Última atualização: 2026-10-18 · HTML: https://console.kolwrite.com/pt/guides/srt-subtitles-api ## A requisição Duas chamadas: iniciar o trabalho e consultá-lo. O `result` de um trabalho `srt` concluído é uma string, não JSON. Esta versão só precisa de curl e jq: ```bash # 1. Start the job. "word_timestamps": false gives one cue per segment. JOB=$(curl -s https://app.kolwrite.com/transcribe \ -H "x-api-key: $KOLWRITE_API_KEY" -H "Content-Type: application/json" \ -d '{"audio_url": "https://example.com/talk.mp3", "model": "oracle", "output_format": "srt", "word_timestamps": false}' \ | jq -r .jobId) # 2. Poll until it is done and save the result string as a .srt file. while true; do REPLY=$(curl -s "https://app.kolwrite.com/transcribe/$JOB" -H "x-api-key: $KOLWRITE_API_KEY") STATUS=$(echo "$REPLY" | jq -r .status) if [ "$STATUS" = "COMPLETED" ]; then echo "$REPLY" | jq -r .result > talk.srt; break; fi if [ "$STATUS" = "FAILED" ]; then echo "$REPLY" | jq -r .error; break; fi sleep 5 done ``` Você pode mandar um vídeo, já que a API lê a faixa de áudio. Arquivos locais passam antes por `POST /upload` (até 100 MiB). Se o vídeo for longo, extraia o áudio com o ffmpeg. A função auxiliar do [guia de edição de vídeo](https://console.kolwrite.com/pt/guides/video-editing-with-ai) faz as duas coisas em Python. ## O que vem no SRT Com `"word_timestamps": false`, a saída traz uma linha por trecho, igual à maioria dos arquivos de legenda: ```text 1 00:00:01,000 --> 00:00:03,750 Hello everyone and welcome to the show. 2 00:00:05,000 --> 00:00:07,750 Today we talk about editing video from a transcript. ``` Por padrão, os tempos por palavra vêm ativados e a API devolve uma linha para cada palavra. Cada linha repete a frase inteira do trecho e coloca a palavra da vez numa tag `` amarela. Isso serve para destacar a leitura em tempo real, não como legenda comum: ```text 1 00:00:01,000 --> 00:00:01,350 Hello everyone and welcome to the show. 2 00:00:01,400 --> 00:00:01,750 Hello everyone and welcome to the show. ``` Se você quer legendas tradicionais, passe `"word_timestamps": false` ou monte as linhas por conta própria a partir das palavras do JSON, como mostramos abaixo. ## Como montar linhas limpas a partir do tempo das palavras Peça `output_format: "json"` e agrupe você mesmo as palavras: limite cada linha a 42 caracteres e 6 segundos, e quebre a linha depois de uma pausa. Assim você controla o comprimento exato, o que faz diferença quando a legenda é gravada direto na imagem do vídeo. srt_tools.py ```python # srt_tools.py — neat subtitle cues from word timings def srt_time(seconds): ms = round(seconds * 1000) h, ms = divmod(ms, 3_600_000) m, ms = divmod(ms, 60_000) s, ms = divmod(ms, 1000) return f"{h:02}:{m:02}:{s:02},{ms:03}" def cues_from_words(words, max_chars=42, max_seconds=6.0, max_gap=0.8): """Group timed words into subtitle cues: (start, end, text).""" cues, line = [], [] for word in words: text = word["word"].strip() if not text: continue if line: length = sum(len(w["word"]) + 1 for w in line) + len(text) if (length > max_chars or word["end"] - line[0]["start"] > max_seconds or word["start"] - line[-1]["end"] > max_gap): cues.append(line) line = [] line.append({"start": word["start"], "end": word["end"], "word": text}) if line: cues.append(line) return [(c[0]["start"], c[-1]["end"], " ".join(w["word"] for w in c)) for c in cues] def cues_from_result(result): """Cues for a whole JSON result; a segment without word times becomes one cue.""" cues = [] for segment in result["segments"]: if segment.get("words"): cues += cues_from_words(segment["words"]) elif segment["text"].strip(): cues.append((segment["start"], segment["end"], segment["text"].strip())) return cues def write_srt(cues, path): with open(path, "w", encoding="utf-8") as out: for number, (start, end, text) in enumerate(cues, 1): out.write(f"{number}\n{srt_time(start)} --> {srt_time(end)}\n{text}\n\n") ``` `cues_from_result(result)` devolve tuplas `(start, end, text)` para o resultado todo e usa os tempos do trecho quando o modelo não traz tempos por palavra. Depois, `write_srt(cues, "talk.srt")` salva o arquivo. ## Legendas traduzidas Passe `translate_to` com o código do idioma e escolha um modelo Oracle (o `oracle_mini` é o mais barato que faz tradução). O texto já sai traduzido; mantenha `word_timestamps` como false para receber um trecho por linha. ```json { "audio_url": "https://example.com/lecture-he.mp4", "model": "oracle_mini", "language": "he", "translate_to": "en", "output_format": "srt", "word_timestamps": false } ``` Para legendar o mesmo vídeo em vários idiomas, rode um trabalho para cada idioma de destino. Como toda tradução automática é um rascunho, revise nomes, números e termos específicos antes de publicar. ## WebVTT, ASS e outros formatos A API gera apenas `json`, `txt` ou `srt`. Se precisar de WebVTT para usar na tag `