Integrations

API

Accesso programmatico all'elaborazione video.

L'API di MediaCopilot fornisce un insieme robusto di endpoint per gestire ed elaborare risorse multimediali, consentendo un'integrazione fluida nei tuoi flussi di lavoro.

La referenza interattiva completa dell'API è disponibile su api.mediacopilot.cires21.ai/docs. Contatta hello@mediacopilot.io per l'accesso all'API.

Autenticazione

Tutte le richieste all'API richiedono un token Bearer nell'intestazione Authorization.

Authorization: Bearer <TUA_API_KEY>

Le chiavi API vengono fornite con il tuo account MediaCopilot.

URL base

https://api.mediacopilot.cires21.ai

Tutti gli endpoint hanno il prefisso /v1.

Pattern comuni

Flusso di caricamento

Caricare un file multimediale segue un processo in 3 passaggi:

Crea la risorsa — POST /v1/assets restituisce un asset_id.
Ottieni URL prefirmati — POST /v1/assets/{asset_id}/start_upload restituisce URL di caricamento prefirmati (uno per parte).
Carica direttamente — Carica le parti del file agli URL prefirmati (lato client).
Conferma il caricamento — POST /v1/assets/{asset_id}/finish_upload con gli ETag di ogni parte.

Pattern di lavoro asincrono

Le operazioni di lunga durata (traduzione, voce fuori campo, ritraduzione parziale, esportazione clip video) seguono un pattern crea-e-interroga:

POST per creare il lavoro — restituisce un job_id.
GET con il job_id per interrogare lo stato fino al completamento.

Esportare su archivio esterno

Tutti gli endpoint di esportazione richiedono un body con external_storage_id che punta a una destinazione di archivio precedentemente configurata.

Modalità di elaborazione

Le risorse possono essere elaborate in due modalità tramite il parametro mc_model:

Modalità	Descrizione
`normal`	Pipeline di elaborazione standard
`turbo`	Elaborazione più veloce con pipeline ottimizzata

Risorse (Assets)

Gestisci le risorse multimediali del tuo tenant.

Crea risorsa

POST /v1/assets

Campo	Tipo	Obbligatorio	Descrizione
`filename`	string	Sì	Nome del file
`template_id`	uuid	No	Template da applicare
`collection_id`	uuid	No	Collezione a cui assegnare
`language_id`	uuid	No	Lingua originale
`external_id`	string	No	Il tuo ID personalizzato (univoco per tenant)
`mc_model`	enum	No	`normal` o `turbo` (predefinito: `normal`)

Elenca risorse

GET /v1/assets

Parametro	Tipo	Obbligatorio	Descrizione
`page`	int	No	Numero di pagina (predefinito: 1)
`items`	int	No	Elementi per pagina (predefinito: 16)
`collection_id`	uuid	No	Filtra per collezione
`entities`	string	No	Filtra per entità (separate da virgole)
`sentiment`	string	No	Filtra per sentiment: Negative, Neutral, Positive
`classification`	string	No	Filtra per classificazione EBU
`speakers`	string	No	Filtra per speaker
`language_id`	uuid	No	Filtra per lingua

Ottieni / Elimina risorsa

GET    /v1/assets/{asset_id}
DELETE /v1/assets/{asset_id}

Ottieni risorsa per ID esterno

GET /v1/external/assets/{external_id}

Caricamento

Inizia caricamento

POST /v1/assets/{asset_id}/start_upload

Campo	Tipo	Obbligatorio	Descrizione
`parts`	int	No	Numero di parti del file (predefinito: 1)

Restituisce URL prefirmati per ogni parte.

Finalizza caricamento

POST /v1/assets/{asset_id}/finish_upload

Campo	Tipo	Obbligatorio	Descrizione
`etags`	string	Sì	ETag restituiti da ogni parte caricata

Lavori di traduzione

Avvia traduzione

POST /v1/assets/{asset_id}/translation_jobs

Campo	Tipo	Obbligatorio	Descrizione
`language_ids`	uuid	Sì	ID delle lingue di destinazione

Ottieni lavoro di traduzione

GET /v1/assets/{asset_id}/translation_jobs/{job_id}

Lavori di voce fuori campo

Avvia voce fuori campo

POST /v1/assets/{asset_id}/process_voice_over_jobs

Campo	Tipo	Obbligatorio	Descrizione
`language_ids`	string	No	Lingue di destinazione (vuoto = tutte quelle del template)

Elenca lavori di voce fuori campo

GET /v1/assets/{asset_id}/process_voice_over_jobs

Ottieni lavoro di voce fuori campo

GET /v1/assets/{asset_id}/process_voice_over_jobs/{job_id}

Lavori di ritraduzione parziale

Crea lavoro di ritraduzione

POST /v1/assets/{asset_id}/partial_retranslation_jobs

Ottieni stato del lavoro di ritraduzione

GET /v1/assets/{asset_id}/partial_retranslation_jobs/{job_id}

Trascrizioni

Elenca trascrizioni

GET /v1/assets/{asset_id}/transcriptions

Ottieni trascrizione

GET /v1/assets/{asset_id}/transcriptions/{transcription_id}

Sottotitoli

Ottieni sottotitoli (inline)

GET /v1/assets/{asset_id}/transcriptions/{transcription_id}/vtt
GET /v1/assets/{asset_id}/transcriptions/{transcription_id}/srt
GET /v1/assets/{asset_id}/transcriptions/{transcription_id}/stl

VTT supporta parametri di query aggiuntivi:

Parametro	Tipo	Predefinito	Descrizione
`flavor`	enum	`standard`	`standard` o `simplified`
`include_sound_descriptions`	bool	`true`	Includi descrizioni audio

Esporta sottotitoli (su archivio esterno)

POST /v1/assets/{asset_id}/transcriptions/{transcription_id}/vtt/export
POST /v1/assets/{asset_id}/transcriptions/{transcription_id}/srt/export
POST /v1/assets/{asset_id}/transcriptions/{transcription_id}/stl/export
POST /v1/assets/{asset_id}/transcriptions/{transcription_id}/json/export

Tutti gli endpoint di esportazione richiedono:

Campo	Tipo	Obbligatorio	Descrizione
`external_storage_id`	uuid	Sì	Destinazione di archivio

Segmenti

Aggiungi segmenti

POST /v1/assets/{asset_id}/transcriptions/{transcription_id}/segments

Campo	Tipo	Obbligatorio	Descrizione
`segments`	array	Sì	Array di oggetti segmento

Ogni oggetto segmento:

Campo	Tipo	Obbligatorio	Descrizione
`text`	string	Sì	Contenuto testuale del segmento
`start_ms`	int	Sì	Tempo di inizio in millisecondi
`end_ms`	int	Sì	Tempo di fine in millisecondi
`speaker`	string	Sì	Identificatore dello speaker
`original_segment_id`	uuid	No	ID del segmento originale (per le traduzioni)

Aggiorna più segmenti

PATCH /v1/assets/{asset_id}/transcriptions/{transcription_id}/segments

Aggiorna un segmento

PATCH /v1/assets/{asset_id}/transcriptions/{transcription_id}/segments/{segment_id}

Campo	Tipo	Obbligatorio	Descrizione
`speaker_id`	uuid	No	Riferimento allo speaker
`text`	string	No	Testo aggiornato
`start_ms`	int	No	Tempo di inizio aggiornato
`end_ms`	int	No	Tempo di fine aggiornato

Metadati

Ottieni tutti i metadati

GET /v1/assets/{asset_id}/metadata

Ottieni metadati specifici

GET /v1/assets/{asset_id}/metadata/{metadata_id}

Esporta metadati

POST /v1/assets/{asset_id}/metadata/{metadata_id}/json/export

Campo	Tipo	Obbligatorio	Descrizione
`external_storage_id`	uuid	Sì	Destinazione di archivio

Ricerca in linguaggio naturale

POST /v1/nl_search

Campo	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Query di ricerca
`asset_id`	uuid	No	Limita la ricerca a una risorsa
`max_results`	int	No	Numero massimo di risultati (predefinito: 10)

Collezioni

Operazioni CRUD

POST   /v1/collections                          # Crea collezione
GET    /v1/collections                           # Elenca collezioni
GET    /v1/collections/{collection_id}           # Ottieni collezione
PATCH  /v1/collections/{collection_id}           # Aggiorna collezione
DELETE /v1/collections/{collection_id}           # Elimina collezione

La creazione richiede:

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome della collezione
`template_id`	uuid	No	Template predefinito

Gestisci risorse della collezione

POST   /v1/collections/{collection_id}/assets    # Aggiungi risorse
DELETE /v1/collections/{collection_id}/assets    # Rimuovi risorse

Entrambi richiedono:

Campo	Tipo	Obbligatorio	Descrizione
`asset_ids`	uuid	Sì	ID delle risorse da aggiungere/rimuovere

Speaker

POST   /v1/assets/{asset_id}/speakers                  # Crea speaker
PATCH  /v1/assets/{asset_id}/speakers/{speaker_id}      # Aggiorna speaker
DELETE /v1/assets/{asset_id}/speakers/{speaker_id}      # Elimina speaker

La creazione richiede:

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome dello speaker

Tracce audio

GET /v1/assets/{asset_id}/audio_tracks                              # Elenca tracce audio
GET /v1/assets/{asset_id}/audio_tracks/{audio_track_id}             # Ottieni traccia audio
GET /v1/assets/{asset_id}/audio_tracks/{audio_track_id}/download_url # Ottieni URL di download

Descrizioni audio

GET    /v1/assets/{asset_id}/sound_descriptions                        # Elenca descrizioni
GET    /v1/assets/{asset_id}/sound_descriptions/{description_id}       # Ottieni descrizione
DELETE /v1/assets/{asset_id}/sound_descriptions/{description_id}       # Elimina descrizione

Analisi video

GET /v1/assets/{asset_id}/camera_shoots    # Ottieni riprese della telecamera
GET /v1/assets/{asset_id}/faces            # Ottieni rilevamenti di volti
GET /v1/assets/{asset_id}/autocenter       # Ottieni dati di autocentratura

Clip video

Crea clip video

POST /v1/assets/{asset_id}/video_clips

Campo	Tipo	Obbligatorio	Descrizione
`video_clips`	array	Sì	Array di oggetti clip

Ogni oggetto clip:

Campo	Tipo	Descrizione
`start_ms`	int	Tempo di inizio della clip in millisecondi
`end_ms`	int	Tempo di fine della clip in millisecondi
`start_frame`	int	Numero del fotogramma di inizio
`end_frame`	int	Numero del fotogramma di fine
`aspect_ratio_x`	int	es. 16
`aspect_ratio_y`	int	es. 9
`autoframing`	bool	Attiva il reframe automatico
`branding_id`	uuid	Branding da applicare
`subtitles_language_id`	uuid	Lingua per i sottotitoli bruciati
`with_sound_descriptions`	bool	Includi descrizioni audio

Elenca / Ottieni clip

GET /v1/assets/{asset_id}/video_clips                  # Elenca clip
GET /v1/assets/{asset_id}/video_clips/{video_id}       # Ottieni clip

Scarica clip

POST /v1/assets/{asset_id}/video_clips/download              # Download sincrono
POST /v1/assets/{asset_id}/video_clips/download_async         # Lavoro di download asincrono
GET  /v1/assets/{asset_id}/video_clips/download_async/{job_id} # Controlla stato download

Esporta clip

POST /v1/assets/{asset_id}/video_clips/{video_clip_id}/export        # Esporta su archivio
POST /v1/assets/{asset_id}/video_clips/{video_clip_id}/async_export  # Esportazione asincrona
GET  /v1/assets/{asset_id}/video_clips/{video_clip_id}/async_export/{job_id} # Controlla stato

Archivio esterno

Operazioni CRUD

POST   /v1/external_storages                           # Aggiungi archivio
GET    /v1/external_storages                           # Elenca archivi
GET    /v1/external_storages/{external_storage_id}     # Ottieni archivio
PATCH  /v1/external_storages/{external_storage_id}     # Aggiorna archivio
DELETE /v1/external_storages/{external_storage_id}     # Elimina archivio

La creazione richiede:

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome dell'archivio
`type`	enum	Sì	`aws_s3`, `azure`, `gcp_storage` o `dummy`
`destination`	object	No	Dettagli del bucket/container (varia per tipo)
`export_path`	string	No	Template di percorso con variabili: `{asset_id}`, `{asset_external_id}`, `{video_clip_id}`
`authentication_data`	object	No	Credenziali (varia per tipo)

Destinazione per tipo:

Tipo	Campi
AWS S3	`bucket_name`, `region`
Azure	`blob_url`
GCP Storage	`bucket_name`

Autenticazione per tipo:

Tipo	Campi
AWS S3	`iam_role_arn`
Azure	`sas_token`
GCP Storage	`credentials` (account di servizio JSON)

Endpoint di amministrazione

GET /v1/admin/external_storages                        # Elenca tutti (admin)
GET /v1/admin/external_storages/{external_storage_id}  # Ottieni (admin)

Template

POST   /v1/templates                    # Crea template
GET    /v1/templates                    # Elenca template
GET    /v1/templates/{template_id}      # Ottieni template
PATCH  /v1/templates/{template_id}      # Aggiorna template
DELETE /v1/templates/{template_id}      # Elimina template

Campi di creazione/aggiornamento:

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome del template
`domain_dictionary_ids`	uuid	No	Dizionari associati
`blacklist_ids`	uuid	No	Liste nere associate
`whitelist_ids`	uuid	No	Liste bianche associate
`translation_language_ids`	uuid	No	Lingue per la traduzione automatica
`voice_over_language_ids`	uuid	No	Lingue per la voce fuori campo automatica
`enabled_ocr`	bool	No	Attiva OCR (predefinito: false)
`voice_over_config`	object	No	`clone_voice` (bool), `mute_original_voice` (bool)

Branding

Branding principale

POST   /v1/brandings                    # Crea branding
GET    /v1/brandings                    # Elenca branding
GET    /v1/brandings/{branding_id}      # Ottieni branding
PATCH  /v1/brandings/{branding_id}      # Aggiorna branding
DELETE /v1/brandings/{branding_id}      # Elimina branding

Varianti di branding

Ogni branding può avere varianti per diversi rapporti d'aspetto.

POST   /v1/brandings/{branding_id}/variants                  # Aggiungi variante
GET    /v1/brandings/{branding_id}/variants                  # Elenca varianti
GET    /v1/brandings/{branding_id}/variants/{variant_id}     # Ottieni variante
PATCH  /v1/brandings/{branding_id}/variants/{variant_id}     # Aggiorna variante
DELETE /v1/brandings/{branding_id}/variants/{variant_id}     # Elimina variante

Campo	Tipo	Obbligatorio	Descrizione
`aspect_ratio`	enum	Sì	`9:16`, `1:1`, `4:5`, `16:9`, `4:3` o `3:4`
`overlay_id`	uuid	No	Overlay da applicare
`intro_id`	uuid	No	Clip di intro
`outro_id`	uuid	No	Clip di outro

Overlay di branding

POST   /v1/branding_overlays                              # Crea overlay
GET    /v1/branding_overlays                              # Elenca overlay
GET    /v1/branding_overlays/{overlay_id}                 # Ottieni overlay
PATCH  /v1/branding_overlays/{overlay_id}                 # Aggiorna overlay
DELETE /v1/branding_overlays/{overlay_id}                 # Elimina overlay
POST   /v1/branding_overlays/{overlay_id}/start_upload    # Inizia caricamento
POST   /v1/branding_overlays/{overlay_id}/finish_upload   # Finalizza caricamento
GET    /v1/branding_overlays/{overlay_id}/upload_jobs/{job_id} # Controlla stato caricamento

Clip di branding

POST   /v1/branding_clips                              # Crea clip
GET    /v1/branding_clips                              # Elenca clip
GET    /v1/branding_clips/{clip_id}                    # Ottieni clip
PATCH  /v1/branding_clips/{clip_id}                    # Aggiorna clip
DELETE /v1/branding_clips/{clip_id}                    # Elimina clip
POST   /v1/branding_clips/{clip_id}/start_upload       # Inizia caricamento
POST   /v1/branding_clips/{clip_id}/finish_upload      # Finalizza caricamento
GET    /v1/branding_clips/{clip_id}/upload_jobs/{job_id} # Controlla stato caricamento

Stili sottotitoli di branding

POST   /v1/branding_subtitle_styles                    # Crea stile
GET    /v1/branding_subtitle_styles                    # Elenca stili
GET    /v1/branding_subtitle_styles/{style_id}         # Ottieni stile
PATCH  /v1/branding_subtitle_styles/{style_id}         # Aggiorna stile
DELETE /v1/branding_subtitle_styles/{style_id}         # Elimina stile

Campo	Tipo	Predefinito	Descrizione
`name`	string	—	Nome dello stile (obbligatorio)
`font_family`	string	—	Famiglia di font (obbligatorio)
`text_color`	hex	—	Colore testo es. `#050B07` (obbligatorio)
`font_size_px`	int	26	Dimensione font in pixel
`font_weight`	int	600	Peso del font
`line_height`	float	1.2	Altezza riga
`vertical_position_pct`	float	0.1	Posizione verticale (% dell'altezza del video)
`shadow_blur`	float	0.0	Raggio di sfocatura dell'ombra
`shadow_color`	hex	—	Colore dell'ombra
`shadow_opacity_pct`	float	1	Opacità dell'ombra
`shadow_offset_x_px`	int	1	Offset X dell'ombra
`shadow_offset_y_px`	int	1	Offset Y dell'ombra
`background_color`	hex	—	Colore di sfondo
`background_opacity`	float	0.0	Opacità dello sfondo
`stroke_color`	hex	`#000000`	Colore del contorno
`stroke_thickness_px`	int	0	Spessore del contorno

Liste di parole

Liste nere

Parole da filtrare dalle trascrizioni.

POST   /v1/blacklists                      # Crea lista nera
GET    /v1/blacklists                      # Elenca liste nere
GET    /v1/blacklists/{blacklist_id}       # Ottieni lista nera
PATCH  /v1/blacklists/{blacklist_id}       # Aggiorna lista nera
DELETE /v1/blacklists/{blacklist_id}       # Elimina lista nera

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome della lista nera
`words`	string	Sì	Parole da filtrare
`language_id`	uuid	Sì	Riferimento lingua
`template_id`	uuid	No	Template associato

Liste bianche

Parole da preservare nelle trascrizioni.

POST   /v1/whitelists                      # Crea lista bianca
GET    /v1/whitelists                      # Elenca liste bianche
GET    /v1/whitelists/{whitelist_id}       # Ottieni lista bianca
PATCH  /v1/whitelists/{whitelist_id}       # Aggiorna lista bianca
DELETE /v1/whitelists/{whitelist_id}       # Elimina lista bianca

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome della lista bianca
`words`	string	Sì	Parole da preservare
`template_id`	uuid	No	Template associato

Dizionari

Mappe di espansione dei termini per la precisione della trascrizione.

POST   /v1/dictionaries                      # Crea dizionario
GET    /v1/dictionaries                      # Elenca dizionari
GET    /v1/dictionaries/{dictionary_id}      # Ottieni dizionario
PATCH  /v1/dictionaries/{dictionary_id}      # Aggiorna dizionario
DELETE /v1/dictionaries/{dictionary_id}      # Elimina dizionario

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome del dizionario
`dictionary`	object	Sì	Mappa chiave-valore, es. `{"IA": ["Intelligenza Artificiale"]}`
`template_id`	uuid	No	Template associato

Lingue

GET /v1/languages                  # Elenca tutte le lingue
GET /v1/languages/{language_id}    # Ottieni dettagli lingua

Viste filtro

POST   /v1/views                    # Crea vista
GET    /v1/views                    # Elenca viste
GET    /v1/views/{view_id}          # Ottieni vista
PATCH  /v1/views/{view_id}          # Aggiorna vista
DELETE /v1/views/{view_id}          # Elimina vista

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome della vista
`filter_params`	array	Sì	Array di condizioni di filtro (minimo 1)

Utilizzo e fatturazione

GET /v1/usages/current_month    # Utilizzo del mese corrente
GET /v1/usages/historical       # Dati storici di utilizzo

Server MCP

Connetti agenti IA per flussi di lavoro automatizzati.

Link e risorse

Canali ufficiali, media kit, contatti.