Captioning API · v1

API de sous-titrage Picute

Envoyez l'URL d'une vidéo et recevez un MP4 sous-titré, un SRT signé et un JSON de transcription. Toute la surface v1 est documentée ci-dessous : démarrage rapide, référence interactive et vérification des webhooks.

Démarrage rapide

Choisissez votre langage. Les extraits ci-dessous envoient un job de sous-titrage avec votre clé d'API — remplacez le placeholder avant exécution.

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"
  }'

Référence de l'API

Tous les endpoints, schémas de requête et codes d'erreur pour v1. Cliquez sur une opération pour déplier les schémas de requête et de réponse.

Webhooks

Picute envoie un webhook signé en POST vers votre URL de callback quand un job de sous-titrage atteint un état terminal. Vérifiez l'en-tête X-Picute-Signature avant de faire confiance au payload.

Événements

caption.completed — Job de sous-titrage réussi. data est la ressource Caption complète avec les URLs de sortie renseignées.
caption.failed — Job de sous-titrage en échec. data.error contient le code et le message d'erreur.

Vérifier la signature

Calculez HMAC-SHA256 sur la chaîne raw 'timestamp.body' avec votre secret webhook, puis comparez en temps constant avec le digest hex contenu dans le champ v1= de l'en-tête.

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