API Video

AVCaption fornisce un’API REST per la gestione video programmatica. Disponibile sul piano Enterprise; accesso preview per Premium su richiesta.

Autenticazione

Due metodi:

Bearer token (JWT) — emesso al login, inviato come header Authorization: Bearer <token>. Usato dalle tue sessioni di dashboard autenticate.

API key — generata nella pagina settings. Formato avc_<64-caratteri-esadecimali>. Inviata come header X-API-Key: <key> o come query param ?api_key=<key>. Utile per server-to-server.

Endpoint

GET    /api/v1/videos               Elenca video (paginato, ?page=1)
GET    /api/v1/videos/:id           Metadata video + token embed
POST   /api/v1/upload               Upload diretto (file piccoli)
POST   /api/v1/upload/init          Avvia sessione di upload chunked
POST   /api/v1/upload/chunk         Carica un chunk
POST   /api/v1/upload/complete      Finalizza upload chunked
PUT    /api/v1/videos/:id           Aggiorna title, allowed_domains
DELETE /api/v1/videos/:id           Elimina video
GET    /api/v1/stats                Stats account: totale video, visualizzazioni, storage usato
GET    /api/v1/embed/:token         Metadata embed pubblico (no auth per video pubblici)
POST   /api/v1/videos/:id/subtitles Carica traccia di sottotitoli (Enterprise)
GET    /api/v1/presets              Elenca preset del player (Enterprise)
POST   /api/v1/presets              Crea preset del player (Enterprise)

Pattern di upload chunked

# Passo 1: init
curl -X POST https://dashboard.avcaption.com/api/v1/upload/init \
  -H "X-API-Key: avc_..." \
  -d '{"filename":"course-lesson-1.mp4","size":1234567890,"title":"Lesson 1"}'
# Restituisce: {"upload_id":"abc123","chunk_size":5242880}

# Passo 2: upload dei chunk (parallelizzabile)
curl -X POST https://dashboard.avcaption.com/api/v1/upload/chunk \
  -H "X-API-Key: avc_..." \
  -H "X-Upload-ID: abc123" \
  -H "X-Chunk-Index: 0" \
  --data-binary @chunk-0.bin
# ...ripetere per ogni chunk

# Passo 3: complete
curl -X POST https://dashboard.avcaption.com/api/v1/upload/complete \
  -H "X-API-Key: avc_..." \
  -d '{"upload_id":"abc123"}'
# Restituisce: {"video_id":"...","embed_token":"...","status":"processing"}

Eventi webhook (Enterprise)

Sottoscrivi gli eventi su un qualsiasi endpoint HTTPS:

• video.uploaded — upload chunked completato
• video.encoded — encoding terminato, pronto a riprodurre
• video.failed — encoding fallito (con dettagli errore)
• view.threshold — il numero di spettatori supera la soglia configurata
• subtitle.translated — traduzione AI completata

Payload webhook firmato con HMAC-SHA256.

Rate limit

• Endpoint di lettura (list, get): 300 req/min per API key
• Endpoint di scrittura (update, delete): 60 req/min
• Endpoint di upload: 60 req/min su init/complete; i chunk in sé non sono rate-limited
• Stats: 60 req/min

I limiti scalano automaticamente per i clienti Enterprise; contatta sales per tariffe personalizzate.

Formato errore

{
  "error": "messaggio d'errore leggibile",
  "code": "machine_readable_error_code",
  "request_id": "x-request-id-for-support-tickets"
}

Per iniziare

L’API REST è inclusa in Enterprise. Genera la tua API key dalla dashboard in Settings → API Keys. Upgrade. Distribuzioni guidate da API comuni: video hosting per LMS, video per clienti di agenzia, prodotti digitali.