SoulDub 動画翻訳 Agent API リファレンス

対象読者：SoulDub の動画翻訳を自動化する Agent、バックエンドサービス、スクリプトです。

この文書は Skill の実行時 API リファレンスであり、scripts/video_translation.py の代わりにはなりません。通常の翻訳では先にスクリプトを使用し、API 呼び出し、認証、冪等性、レート制限、結果のダウンロード、エラーコードをデバッグするときに参照してください。

1. Agent クイックリファレンス

• 現在の API ベース URL：https://xxx.com/api/v1
• 外部 API パスは /api/v1/... 配下です。
• すべての /api/v1/... エンドポイントには Agent API key が必要です。Authorization: Bearer ${AGENT_API_KEY} を優先してください。
• バイナリ動画のアップロードはストレージの presigned URL に PUT {presignedUrl} で直接送信し、API key は付けません。
• メディアゲートウェイ URL は API key なしで直接ダウンロードします。
• 字幕ダウンロードは Agent API エンドポイントのため API key が必要です。
• タスク作成と再翻訳には安定した Idempotency-Key が必要です。
• API key、アップロード用 presigned URL、一時的なメディア URL、署名パラメータをログ、状態ファイル、テストレポート、プロンプトに保存しないでください。
• 429 が返った場合は Retry-After に従って待機し、同時実行数の制限にも従ってください。
• 一時 URL が期限切れになった場合は、結果エンドポイントから新しい URL を取得します。

2. 呼び出しフロー

任意の再翻訳：

POST /video-translations/{existingTaskId}/retranslate

3. 認証と共通ルール

Agent API は次の2種類の認証ヘッダーをサポートします。最初の方法を推奨します。

Authorization: Bearer ${AGENT_API_KEY}

X-API-Key: ${AGENT_API_KEY}

一般的な JSON リクエストヘッダー：

Content-Type: application/json
Accept: application/json
Authorization: Bearer ${AGENT_API_KEY}
X-Request-Id: agent-run-20260704-0001

X-Request-Id は任意です。指定する場合は 8..64 文字で、A-Z a-z 0-9 _ . : - のみ使用できます。サーバーはレスポンスヘッダーに最終的な request id を返します。

成功レスポンス：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

エラーレスポンス：

{
  "code": -1,
  "message": "INVALID_REQUEST",
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Validation failed.",
    "requestId": "req_abc123",
    "details": {}
  }
}

デバッグでは次の順に確認します。

1. HTTP ステータス
2. error.code
3. error.details
4. レスポンスヘッダーの X-Request-Id

レート制限のレスポンスヘッダーが返ることがあります。

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1782300000

429 の場合は Retry-After の秒数だけ待ってから再試行してください。

4. 動画アップロード

4.1 アップロードを開始する

POST /video-uploads/initiate

{
  "filename": "demo.mp4",
  "contentType": "video/mp4",
  "fileSizeBytes": 342556
}

レスポンスの fileId、uploadId、key、bucket を保存します。アップロード完了とタスク作成で使用します。

4.2 パート URL を取得する

POST /video-uploads/presign-part

返された presignedUrl は現在のアップロードにだけ使用し、ログや状態ファイルに保存しないでください。partNumber は 1..10000、URL の有効期間はサーバーによって 60..86400 秒に制限されます。

4.3 動画バイトをアップロードする

PUT {presignedUrl}
Content-Type: video/mp4

このリクエストは Agent API ではありません。Authorization と X-API-Key を付けず、URL が期限切れの場合は presign-part をもう一度呼び出します。

4.4 アップロードを完了する

POST /video-uploads/complete

data.success == true、data.status == "completed"、data.fileId が開始レスポンスの fileId と一致することを確認します。

5. 翻訳タスクを作成する

POST /video-translations
Idempotency-Key: ${UNIQUE_IDEMPOTENCY_KEY}

リクエストには fileId、videoDurationSeconds、sourceLanguage、targetLanguage を含めます。speakerCount と allowDynamicDuration は任意です。targetLanguage に auto は指定できません。

taskId、fileId、creditsConsumed、使用した Idempotency-Key を保存してください。クレジットは動画の分数単位で切り上げて計算されます。

同じ Key と同じ本文を再送した場合は二重課金されません。同じ Key で本文が異なる場合は IDEMPOTENCY_KEY_REUSED、処理中の場合は IDEMPOTENCY_REQUEST_IN_PROGRESS が返ります。タイムアウト時は同じ本文と Key で再試行してください。

6. タスクの進捗を確認する

GET /video-translations/{taskId}

status は pending、processing、completed、failed、cancelled のいずれかです。作成から約2秒後に最初の確認を行い、未完了の場合は 2s -> 5s -> 10s -> 20s -> 30s と間隔を広げます。completed、failed、cancelled のいずれかになるまで確認を続けてください。

7. 結果を取得する

GET /video-translations/{taskId}/results?expiresIn=600
GET /video-translations/{taskId}/results/files/{variant}?expiresIn=600
GET /video-translations/{taskId}/results/subtitles/{variant}

結果には最終 MP4、音声、背景音、入力字幕、翻訳字幕、バイリンガル字幕が含まれる場合があります。access=media_gateway の URL は API key なしでダウンロードします。字幕 URL に requiresAuthorization=true がある場合は API key が必要です。

一時 URL が期限切れになった場合は結果エンドポイントを再度呼び出します。字幕エンドポイントは JSON ではなく SRT テキストを返し、?download=1 で添付ファイルとして取得できます。

8. 再翻訳

POST /video-translations/{existingTaskId}/retranslate
Idempotency-Key: ${UNIQUE_IDEMPOTENCY_KEY}

既存タスクが completed、failed、cancelled の場合に実行できます。リクエスト本文は空でも構いません。再翻訳は新しいタスクを作成し、クレジットと同時実行制限の対象になります。

9. 復旧可能な状態

apiBase、fileId、uploadId、key、taskId、idempotencyKey、言語、status を保存できます。Agent API key、presigned URL、一時メディア URL、署名パラメータは保存しないでください。

uploadId と key があれば未完了パートの URL を再生成できます。taskId があれば GET /video-translations/{taskId} から再開し、URL が期限切れなら結果エンドポイントから更新します。

10. エラーコード

UNAUTHORIZED、API_KEY_INVALID、API_KEY_EXPIRED、API_KEY_REVOKED は認証エラーです。RATE_LIMITED と CONCURRENCY_LIMIT_REACHED は待機して再試行します。INSUFFICIENT_CREDITS、INVALID_REQUEST、INVALID_LANGUAGE、FILE_TOO_LARGE は入力またはアカウント状態を確認してください。

TASK_NOT_COMPLETED と RESULT_NOT_READY は処理完了まで待機します。TASK_NOT_FOUND、SUBTITLE_NOT_FOUND、FINAL_VIDEO_EXPIRED は詳細を確認してから再処理または再取得します。5xx は上限付きの指数バックオフで再試行できます。

11. 外部呼び出しに関する注意

• 呼び出しには Base URL、Agent API key、ここに記載されたエンドポイントだけが必要です。
• presigned URL と一時メディア URL をキャッシュまたは長期保存しないでください。
• API key やダウンロード URL をログや会話コンテキストに書き込まないでください。
• ダウンロード URL が期限切れになったら結果エンドポイントから新しい URL を取得してください。