Captioning API · v1

Picute キャプションAPI

ビデオURLを送信すると、キャプション焼き込み済みのMP4、署名付きSRT、トランスクリプトJSONを取得できます。v1の全仕様は以下に記載しています — クイックスタート、インタラクティブリファレンス、Webhook検証まで。

クイックスタート

好みの言語を選んでください。以下のコードはAPIキーでキャプションジョブを送信します — 実行前にプレースホルダーをご自分のキーに置き換えてください。

curl -X POST https://picute.net/api/v1/captions \
  -H "Authorization: Bearer pk_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://cdn.example.com/clip.mp4",
    "language": "auto",
    "preset": "default",
    "callback_url": "https://api.your-app.com/webhooks/picute"
  }'

APIリファレンス

v1のすべてのエンドポイント、リクエストスキーマ、エラーコードです。操作をクリックすると、リクエストとレスポンスのスキーマが展開されます。

Webhook

キャプションジョブが終了状態に達すると、Picuteは署名付きWebhookをコールバックURLにPOSTします。ペイロードを信頼する前に必ず X-Picute-Signature ヘッダーを検証してください。

イベント

caption.completed — キャプションジョブ成功。data は出力URLが入った完全な Caption リソースです。
caption.failed — キャプションジョブ失敗。data.error にエラーコードとメッセージが入っています。

署名の検証

Webhookシークレットを使って raw 'timestamp.body' 文字列の HMAC-SHA256 を計算し、X-Picute-Signature ヘッダーの v1= フィールドに入っている hex ダイジェストと定数時間で比較してください。

import hmac, hashlib, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = "<your_webhook_secret_from_dashboard>"
TOLERANCE_SECONDS = 5 * 60

def verify(req):
    header = req.headers.get("X-Picute-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    timestamp = int(parts.get("t", "0"))
    received = parts.get("v1", "")
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}.{req.get_data(as_text=True)}".encode("utf-8")
    expected = hmac.new(SECRET.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

@app.post("/webhooks/picute")
def hook():
    if not verify(request):
        abort(401)
    payload = request.get_json()
    print(payload["event"], payload["data"]["id"])
    return "", 204