Integrations

API

Acceso programático al procesamiento de vídeo.

La API de MediaCopilot proporciona un conjunto robusto de endpoints para gestionar y procesar recursos multimedia, permitiendo una integración fluida en tus flujos de trabajo.

La referencia interactiva completa de la API está disponible en api.mediacopilot.cires21.ai/docs. Contacta con hello@mediacopilot.io para acceso a la API.

Autenticación

Todas las solicitudes a la API requieren un token Bearer en la cabecera Authorization.

Authorization: Bearer <TU_API_KEY>

Las claves de API se proporcionan con tu cuenta de MediaCopilot.

URL base

https://api.mediacopilot.cires21.ai

Todos los endpoints tienen el prefijo /v1.

Patrones comunes

Flujo de subida

Subir un archivo multimedia sigue un proceso de 3 pasos:

Crear el recurso — POST /v1/assets devuelve un asset_id.
Obtener URLs prefirmadas — POST /v1/assets/{asset_id}/start_upload devuelve URLs de subida prefirmadas (una por parte).
Subir directamente — Sube las partes del archivo a las URLs prefirmadas (en el cliente).
Confirmar la subida — POST /v1/assets/{asset_id}/finish_upload con los ETags de cada parte.

Patrón de trabajo asíncrono

Las operaciones de larga duración (traducción, voz en off, retraducción parcial, exportación de clips de vídeo) siguen un patrón de crear-y-consultar:

POST para crear el trabajo — devuelve un job_id.
GET con el job_id para consultar el estado hasta la finalización.

Exportar a almacenamiento externo

Todos los endpoints de exportación requieren un cuerpo con external_storage_id que apunte a un destino de almacenamiento previamente configurado.

Modos de procesamiento

Los recursos pueden procesarse en dos modos mediante el parámetro mc_model:

Modo	Descripción
`normal`	Pipeline de procesamiento estándar
`turbo`	Procesamiento más rápido con pipeline optimizado

Recursos (Assets)

Gestiona los recursos multimedia de tu tenant.

Crear recurso

POST /v1/assets

Campo	Tipo	Obligatorio	Descripción
`filename`	string	Sí	Nombre del archivo
`template_id`	uuid	No	Plantilla a aplicar
`collection_id`	uuid	No	Colección a la que asignar
`language_id`	uuid	No	Idioma original
`external_id`	string	No	Tu ID personalizado (único por tenant)
`mc_model`	enum	No	`normal` o `turbo` (por defecto: `normal`)

Listar recursos

GET /v1/assets

Parámetro	Tipo	Obligatorio	Descripción
`page`	int	No	Número de página (por defecto: 1)
`items`	int	No	Elementos por página (por defecto: 16)
`collection_id`	uuid	No	Filtrar por colección
`entities`	string	No	Filtrar por entidades (separadas por comas)
`sentiment`	string	No	Filtrar por sentimiento: Negative, Neutral, Positive
`classification`	string	No	Filtrar por clasificación EBU
`speakers`	string	No	Filtrar por locutores
`language_id`	uuid	No	Filtrar por idioma

Obtener / Eliminar recurso

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

Obtener recurso por ID externo

GET /v1/external/assets/{external_id}

Subida

Iniciar subida

POST /v1/assets/{asset_id}/start_upload

Campo	Tipo	Obligatorio	Descripción
`parts`	int	No	Número de partes del archivo (por defecto: 1)

Devuelve URLs prefirmadas para cada parte.

Finalizar subida

POST /v1/assets/{asset_id}/finish_upload

Campo	Tipo	Obligatorio	Descripción
`etags`	string	Sí	ETags devueltos de cada parte subida

Trabajos de traducción

Iniciar traducción

POST /v1/assets/{asset_id}/translation_jobs

Campo	Tipo	Obligatorio	Descripción
`language_ids`	uuid	Sí	IDs de idiomas de destino

Obtener trabajo de traducción

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

Trabajos de voz en off

Iniciar voz en off

POST /v1/assets/{asset_id}/process_voice_over_jobs

Campo	Tipo	Obligatorio	Descripción
`language_ids`	string	No	Idiomas de destino (vacío = todos los de la plantilla)

Listar trabajos de voz en off

GET /v1/assets/{asset_id}/process_voice_over_jobs

Obtener trabajo de voz en off

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

Trabajos de retraducción parcial

Crear trabajo de retraducción

POST /v1/assets/{asset_id}/partial_retranslation_jobs

Obtener estado del trabajo de retraducción

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

Transcripciones

Listar transcripciones

GET /v1/assets/{asset_id}/transcriptions

Obtener transcripción

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

Subtítulos

Obtener subtítulos (en línea)

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 admite parámetros de consulta adicionales:

Parámetro	Tipo	Por defecto	Descripción
`flavor`	enum	`standard`	`standard` o `simplified`
`include_sound_descriptions`	bool	`true`	Incluir descripciones de sonido

Exportar subtítulos (a almacenamiento externo)

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

Todos los endpoints de exportación requieren:

Campo	Tipo	Obligatorio	Descripción
`external_storage_id`	uuid	Sí	Destino de almacenamiento

Segmentos

Añadir segmentos

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

Campo	Tipo	Obligatorio	Descripción
`segments`	array	Sí	Array de objetos de segmento

Cada objeto de segmento:

Campo	Tipo	Obligatorio	Descripción
`text`	string	Sí	Contenido de texto del segmento
`start_ms`	int	Sí	Tiempo de inicio en milisegundos
`end_ms`	int	Sí	Tiempo de fin en milisegundos
`speaker`	string	Sí	Identificador del locutor
`original_segment_id`	uuid	No	ID del segmento original (para traducciones)

Actualizar múltiples segmentos

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

Actualizar un segmento

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

Campo	Tipo	Obligatorio	Descripción
`speaker_id`	uuid	No	Referencia al locutor
`text`	string	No	Texto actualizado
`start_ms`	int	No	Tiempo de inicio actualizado
`end_ms`	int	No	Tiempo de fin actualizado

Metadatos

Obtener todos los metadatos

GET /v1/assets/{asset_id}/metadata

Obtener metadatos específicos

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

Exportar metadatos

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

Campo	Tipo	Obligatorio	Descripción
`external_storage_id`	uuid	Sí	Destino de almacenamiento

Búsqueda en lenguaje natural

POST /v1/nl_search

Campo	Tipo	Obligatorio	Descripción
`query`	string	Sí	Consulta de búsqueda
`asset_id`	uuid	No	Limitar búsqueda a un recurso
`max_results`	int	No	Máximo de resultados (por defecto: 10)

Colecciones

Operaciones CRUD

POST   /v1/collections                          # Crear colección
GET    /v1/collections                           # Listar colecciones
GET    /v1/collections/{collection_id}           # Obtener colección
PATCH  /v1/collections/{collection_id}           # Actualizar colección
DELETE /v1/collections/{collection_id}           # Eliminar colección

Crear requiere:

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la colección
`template_id`	uuid	No	Plantilla por defecto

Gestionar recursos de la colección

POST   /v1/collections/{collection_id}/assets    # Añadir recursos
DELETE /v1/collections/{collection_id}/assets    # Eliminar recursos

Ambos requieren:

Campo	Tipo	Obligatorio	Descripción
`asset_ids`	uuid	Sí	IDs de recursos a añadir/eliminar

Locutores

POST   /v1/assets/{asset_id}/speakers                  # Crear locutor
PATCH  /v1/assets/{asset_id}/speakers/{speaker_id}      # Actualizar locutor
DELETE /v1/assets/{asset_id}/speakers/{speaker_id}      # Eliminar locutor

Crear requiere:

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre del locutor

Pistas de audio

GET /v1/assets/{asset_id}/audio_tracks                              # Listar pistas de audio
GET /v1/assets/{asset_id}/audio_tracks/{audio_track_id}             # Obtener pista de audio
GET /v1/assets/{asset_id}/audio_tracks/{audio_track_id}/download_url # Obtener URL de descarga

Descripciones de sonido

GET    /v1/assets/{asset_id}/sound_descriptions                        # Listar descripciones
GET    /v1/assets/{asset_id}/sound_descriptions/{description_id}       # Obtener descripción
DELETE /v1/assets/{asset_id}/sound_descriptions/{description_id}       # Eliminar descripción

Análisis de vídeo

GET /v1/assets/{asset_id}/camera_shoots    # Obtener planos de cámara
GET /v1/assets/{asset_id}/faces            # Obtener detecciones de rostros
GET /v1/assets/{asset_id}/autocenter       # Obtener datos de autocentrado

Clips de vídeo

Crear clips de vídeo

POST /v1/assets/{asset_id}/video_clips

Campo	Tipo	Obligatorio	Descripción
`video_clips`	array	Sí	Array de objetos de clip

Cada objeto de clip:

Campo	Tipo	Descripción
`start_ms`	int	Tiempo de inicio del clip en milisegundos
`end_ms`	int	Tiempo de fin del clip en milisegundos
`start_frame`	int	Número de fotograma de inicio
`end_frame`	int	Número de fotograma de fin
`aspect_ratio_x`	int	p.ej. 16
`aspect_ratio_y`	int	p.ej. 9
`autoframing`	bool	Activar encuadre automático
`branding_id`	uuid	Marca a aplicar
`subtitles_language_id`	uuid	Idioma para subtítulos quemados
`with_sound_descriptions`	bool	Incluir descripciones de sonido

Listar / Obtener clips

GET /v1/assets/{asset_id}/video_clips                  # Listar clips
GET /v1/assets/{asset_id}/video_clips/{video_id}       # Obtener clip

Descargar clips

POST /v1/assets/{asset_id}/video_clips/download              # Descarga síncrona
POST /v1/assets/{asset_id}/video_clips/download_async         # Trabajo de descarga asíncrona
GET  /v1/assets/{asset_id}/video_clips/download_async/{job_id} # Comprobar estado de descarga

Exportar clips

POST /v1/assets/{asset_id}/video_clips/{video_clip_id}/export        # Exportar a almacenamiento
POST /v1/assets/{asset_id}/video_clips/{video_clip_id}/async_export  # Exportación asíncrona
GET  /v1/assets/{asset_id}/video_clips/{video_clip_id}/async_export/{job_id} # Comprobar estado

Almacenamiento externo

Operaciones CRUD

POST   /v1/external_storages                           # Añadir almacenamiento
GET    /v1/external_storages                           # Listar almacenamientos
GET    /v1/external_storages/{external_storage_id}     # Obtener almacenamiento
PATCH  /v1/external_storages/{external_storage_id}     # Actualizar almacenamiento
DELETE /v1/external_storages/{external_storage_id}     # Eliminar almacenamiento

Crear requiere:

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre del almacenamiento
`type`	enum	Sí	`aws_s3`, `azure`, `gcp_storage` o `dummy`
`destination`	object	No	Detalles del bucket/contenedor (varía por tipo)
`export_path`	string	No	Plantilla de ruta con variables: `{asset_id}`, `{asset_external_id}`, `{video_clip_id}`
`authentication_data`	object	No	Credenciales (varía por tipo)

Destino por tipo:

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

Autenticación por tipo:

Tipo	Campos
AWS S3	`iam_role_arn`
Azure	`sas_token`
GCP Storage	`credentials` (cuenta de servicio JSON)

Endpoints de administración

GET /v1/admin/external_storages                        # Listar todos (admin)
GET /v1/admin/external_storages/{external_storage_id}  # Obtener (admin)

Plantillas

POST   /v1/templates                    # Crear plantilla
GET    /v1/templates                    # Listar plantillas
GET    /v1/templates/{template_id}      # Obtener plantilla
PATCH  /v1/templates/{template_id}      # Actualizar plantilla
DELETE /v1/templates/{template_id}      # Eliminar plantilla

Campos de creación/actualización:

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la plantilla
`domain_dictionary_ids`	uuid	No	Diccionarios asociados
`blacklist_ids`	uuid	No	Listas negras asociadas
`whitelist_ids`	uuid	No	Listas blancas asociadas
`translation_language_ids`	uuid	No	Idiomas para auto-traducción
`voice_over_language_ids`	uuid	No	Idiomas para voz en off automática
`enabled_ocr`	bool	No	Activar OCR (por defecto: false)
`voice_over_config`	object	No	`clone_voice` (bool), `mute_original_voice` (bool)

Marcas (Brandings)

Marcas principales

POST   /v1/brandings                    # Crear marca
GET    /v1/brandings                    # Listar marcas
GET    /v1/brandings/{branding_id}      # Obtener marca
PATCH  /v1/brandings/{branding_id}      # Actualizar marca
DELETE /v1/brandings/{branding_id}      # Eliminar marca

Variantes de marca

Cada marca puede tener variantes para distintas relaciones de aspecto.

POST   /v1/brandings/{branding_id}/variants                  # Añadir variante
GET    /v1/brandings/{branding_id}/variants                  # Listar variantes
GET    /v1/brandings/{branding_id}/variants/{variant_id}     # Obtener variante
PATCH  /v1/brandings/{branding_id}/variants/{variant_id}     # Actualizar variante
DELETE /v1/brandings/{branding_id}/variants/{variant_id}     # Eliminar variante

Campo	Tipo	Obligatorio	Descripción
`aspect_ratio`	enum	Sí	`9:16`, `1:1`, `4:5`, `16:9`, `4:3` o `3:4`
`overlay_id`	uuid	No	Overlay a aplicar
`intro_id`	uuid	No	Clip de intro
`outro_id`	uuid	No	Clip de outro

Overlays de marca

POST   /v1/branding_overlays                              # Crear overlay
GET    /v1/branding_overlays                              # Listar overlays
GET    /v1/branding_overlays/{overlay_id}                 # Obtener overlay
PATCH  /v1/branding_overlays/{overlay_id}                 # Actualizar overlay
DELETE /v1/branding_overlays/{overlay_id}                 # Eliminar overlay
POST   /v1/branding_overlays/{overlay_id}/start_upload    # Iniciar subida
POST   /v1/branding_overlays/{overlay_id}/finish_upload   # Finalizar subida
GET    /v1/branding_overlays/{overlay_id}/upload_jobs/{job_id} # Comprobar estado de subida

Clips de marca

POST   /v1/branding_clips                              # Crear clip
GET    /v1/branding_clips                              # Listar clips
GET    /v1/branding_clips/{clip_id}                    # Obtener clip
PATCH  /v1/branding_clips/{clip_id}                    # Actualizar clip
DELETE /v1/branding_clips/{clip_id}                    # Eliminar clip
POST   /v1/branding_clips/{clip_id}/start_upload       # Iniciar subida
POST   /v1/branding_clips/{clip_id}/finish_upload      # Finalizar subida
GET    /v1/branding_clips/{clip_id}/upload_jobs/{job_id} # Comprobar estado de subida

Estilos de subtítulos de marca

POST   /v1/branding_subtitle_styles                    # Crear estilo
GET    /v1/branding_subtitle_styles                    # Listar estilos
GET    /v1/branding_subtitle_styles/{style_id}         # Obtener estilo
PATCH  /v1/branding_subtitle_styles/{style_id}         # Actualizar estilo
DELETE /v1/branding_subtitle_styles/{style_id}         # Eliminar estilo

Campo	Tipo	Por defecto	Descripción
`name`	string	—	Nombre del estilo (obligatorio)
`font_family`	string	—	Familia de fuente (obligatorio)
`text_color`	hex	—	Color de texto p.ej. `#050B07` (obligatorio)
`font_size_px`	int	26	Tamaño de fuente en píxeles
`font_weight`	int	600	Peso de la fuente
`line_height`	float	1.2	Altura de línea
`vertical_position_pct`	float	0.1	Posición vertical (% de la altura del vídeo)
`shadow_blur`	float	0.0	Radio de desenfoque de sombra
`shadow_color`	hex	—	Color de sombra
`shadow_opacity_pct`	float	1	Opacidad de sombra
`shadow_offset_x_px`	int	1	Desplazamiento X de sombra
`shadow_offset_y_px`	int	1	Desplazamiento Y de sombra
`background_color`	hex	—	Color de fondo
`background_opacity`	float	0.0	Opacidad de fondo
`stroke_color`	hex	`#000000`	Color de contorno
`stroke_thickness_px`	int	0	Grosor del contorno

Listas de palabras

Listas negras

Palabras a filtrar de las transcripciones.

POST   /v1/blacklists                      # Crear lista negra
GET    /v1/blacklists                      # Listar listas negras
GET    /v1/blacklists/{blacklist_id}       # Obtener lista negra
PATCH  /v1/blacklists/{blacklist_id}       # Actualizar lista negra
DELETE /v1/blacklists/{blacklist_id}       # Eliminar lista negra

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la lista negra
`words`	string	Sí	Palabras a filtrar
`language_id`	uuid	Sí	Referencia de idioma
`template_id`	uuid	No	Plantilla asociada

Listas blancas

Palabras a preservar en las transcripciones.

POST   /v1/whitelists                      # Crear lista blanca
GET    /v1/whitelists                      # Listar listas blancas
GET    /v1/whitelists/{whitelist_id}       # Obtener lista blanca
PATCH  /v1/whitelists/{whitelist_id}       # Actualizar lista blanca
DELETE /v1/whitelists/{whitelist_id}       # Eliminar lista blanca

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la lista blanca
`words`	string	Sí	Palabras a preservar
`template_id`	uuid	No	Plantilla asociada

Diccionarios

Mapas de expansión de términos para la precisión de transcripción.

POST   /v1/dictionaries                      # Crear diccionario
GET    /v1/dictionaries                      # Listar diccionarios
GET    /v1/dictionaries/{dictionary_id}      # Obtener diccionario
PATCH  /v1/dictionaries/{dictionary_id}      # Actualizar diccionario
DELETE /v1/dictionaries/{dictionary_id}      # Eliminar diccionario

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre del diccionario
`dictionary`	object	Sí	Mapa clave-valor, p.ej. `{"IA": ["Inteligencia Artificial"]}`
`template_id`	uuid	No	Plantilla asociada

Idiomas

GET /v1/languages                  # Listar todos los idiomas
GET /v1/languages/{language_id}    # Obtener detalles del idioma

Vistas de filtro

POST   /v1/views                    # Crear vista
GET    /v1/views                    # Listar vistas
GET    /v1/views/{view_id}          # Obtener vista
PATCH  /v1/views/{view_id}          # Actualizar vista
DELETE /v1/views/{view_id}          # Eliminar vista

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la vista
`filter_params`	array	Sí	Array de condiciones de filtro (mínimo 1)

Uso y facturación

GET /v1/usages/current_month    # Uso del mes actual
GET /v1/usages/historical       # Datos históricos de uso

Servidor MCP

Conecta agentes de IA para flujos de trabajo automatizados.

Enlaces y recursos

Canales oficiales, kit de medios, contacto.