動画URLをPOSTし、IDを保存します
APIキーと動画URLをPOST /v1/transcriptionsに送ります。Pythonでも、普段のHTTPクライアントでも使えます。wait=60を付けると最大60秒待ちます。指定できる項目はAPIリファレンスで確認できます。
APIキーはダッシュボードで作成し、サーバーやスクリプトから使います。作成リクエストが成功したら、返ってきた文字起こしIDを保存してください。待ち時間を過ぎても処理は続きます。同じ動画を再送せず、GET /v1/transcriptions/:idで続きを確認します。
queued、fetching、transcribingは処理の途中です。completedになったらテキストを取得し、failedならエラーを処理します。応答が遅れた場合や動画を取得できなかった場合に、空のテキストを「成功」として返さない設計にしてください。
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'transcript_sourceで取得元を確認します
字幕を使った場合は、その種類もレスポンスで分かります。billed_minutesは動画の長さを分単位で切り上げた値です。各フィールドは文字起こしオブジェクトにまとめています。
取得元を記録するアプリでは、transcript_sourceとcaption_kindも保存します。投稿者がアップロードした字幕には単語ごとのタイムスタンプがありません。自動生成字幕には単語の開始時刻、AI文字起こしには開始・終了時刻と信頼度があります。単語のデータが必要なときだけinclude=wordsを付けます。
セグメントには開始・終了位置が秒で入ります。再生位置に移動するUIや、録音と対応したメモに使えます。以下のJSONは構造を示す例です。リクエスト例の動画を引用したものではありません。
{
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"status": "completed",
"transcript_source": "youtube_captions",
"caption_kind": "auto_generated",
"language": "en",
"billed_minutes": 4,
"transcript": {
"text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
"segments": [
{ "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
]
}
}字幕の取得とAI文字起こしを使い分けます
sourceの初期値はautoです。captions（字幕のみ）では、使える字幕がなければno_captionsになり、課金しません。sttなら常に音声から文字起こしします。言語や話者分離との組み合わせは取得方法の設定で確認できます。
公開された字幕そのものが必要ならcaptions（字幕のみ）を選びます。音声から作り直す場合や話者分離が必要な場合はsttを使います。autoでもdiarize=trueなら字幕を使わずAI文字起こしに進みます。captionsと話者分離は併用できず、リクエストはエラーになります。
languageを指定した場合、字幕はその言語と一致する必要があります。autoなら動画の元の言語を使い、自動翻訳字幕は取得しません。AI文字起こしで言語を指定しても、別の言語への翻訳にはなりません。
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}再送する前に、エラーと既存のジョブを確認します
非公開動画、年齢制限付き動画、進行中のライブ配信は、再送しても取得できません。no_captionsなら、字幕の代わりに音声から文字起こししてよいかを判断します。まだ処理中なら同じIDで確認してください。エラー一覧を使い、原因ごとに対応を分けます。
作成リクエストを再試行する場合はIdempotency-Keyの仕様に従います。最近の文字起こしを再利用する設定は、同じ動画と同じオプションを照合する別の機能です。キャッシュの利用だけでは無料になるとは限りません。完了済みのジョブをIDで読み直す場合は、分数を消費しません。
同じエンドポイントでTikTokやInstagramなどにも対応できます。YouTube、X、TikTok、Blueskyは字幕を優先する例ですが、全プラットフォームの一覧ではありません。ソース別の対応表に合わせ、使えない設定をUIで選ばせないようにします。