Integrations

API

Programmatic access to video processing.

The MediaCopilot API provides a robust set of endpoints to manage and process media assets, enabling seamless integration into your workflows.

Full interactive API reference is available at api.mediacopilot.cires21.ai/docs. Contact hello@mediacopilot.io for API access.

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer <YOUR_API_KEY>

API keys are provided with your MediaCopilot account.

Base URL

https://api.mediacopilot.cires21.ai

All endpoints are prefixed with /v1.

Common Patterns

Upload Flow

Uploading a media file follows a 3-step process:

Create the asset — POST /v1/assets returns an asset_id.
Get presigned URLs — POST /v1/assets/{asset_id}/start_upload returns presigned upload URLs (one per part).
Upload directly — Upload file parts to the presigned URLs (client-side).
Confirm upload — POST /v1/assets/{asset_id}/finish_upload with ETags from each part.

Async Job Pattern

Long-running operations (translation, voice over, retranslation, video clip export) follow a create-then-poll pattern:

POST to create the job — returns a job_id.
GET with the job_id to poll status until completion.

Export to External Storage

All export endpoints require a body with external_storage_id pointing to a previously configured storage destination.

Processing Modes

Assets can be processed in two modes via the mc_model parameter:

Mode	Description
`normal`	Standard processing pipeline
`turbo`	Faster processing with optimized pipeline

Assets

Manage media assets in your tenant.

Create Asset

POST /v1/assets

Field	Type	Required	Description
`filename`	string	Yes	Name of the file
`name`	string	No	Custom display name for the asset
`template_id`	uuid	No	Template to apply
`collection_id`	uuid	No	Collection to assign to
`language_id`	uuid	No	Original language
`external_id`	string	No	Your custom ID (unique per tenant)
`mc_model`	enum	No	`normal` or `turbo` (default: `normal`)

List Assets

GET /v1/assets

Parameter	Type	Required	Description
`page`	int	No	Page number (default: 1)
`items`	int	No	Items per page (default: 16)
`collection_id`	uuid	No	Filter by collection
`entities`	string	No	Filter by entities (comma-separated)
`sentiment`	string	No	Filter by sentiment: Negative, Neutral, Positive
`classification`	string	No	Filter by EBU classification
`speakers`	string	No	Filter by speakers
`language_id`	uuid	No	Filter by language

Get / Delete Asset

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

Get Asset by External ID

GET /v1/external/assets/{external_id}

Upload

Start Upload

POST /v1/assets/{asset_id}/start_upload

Field	Type	Required	Description
`parts`	int	No	Number of file parts (default: 1)

Returns presigned URLs for each part.

Finish Upload

POST /v1/assets/{asset_id}/finish_upload

Field	Type	Required	Description
`etags`	string	Yes	ETags returned from each part upload

Translation Jobs

Start Translation

POST /v1/assets/{asset_id}/translation_jobs

Field	Type	Required	Description
`language_ids`	uuid	Yes	Target language IDs

Get Translation Job

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

Voice Over Jobs

Start Voice Over

POST /v1/assets/{asset_id}/process_voice_over_jobs

Field	Type	Required	Description
`language_ids`	string	No	Target languages (blank for all tracks in template)

List Voice Over Jobs

GET /v1/assets/{asset_id}/process_voice_over_jobs

Get Voice Over Job

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

Partial Retranslation Jobs

Create Retranslation Job

POST /v1/assets/{asset_id}/partial_retranslation_jobs

Get Retranslation Job Status

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

Transcriptions

List Transcriptions

GET /v1/assets/{asset_id}/transcriptions

Get Transcription

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

Subtitles

Get Subtitles (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 supports additional query parameters:

Parameter	Type	Default	Description
`flavor`	enum	`standard`	`standard` or `simplified`
`include_sound_descriptions`	bool	`true`	Include sound descriptions

Export Subtitles (to External Storage)

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

All export endpoints require:

Field	Type	Required	Description
`external_storage_id`	uuid	Yes	Target storage destination

Segments

Add Segments

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

Field	Type	Required	Description
`segments`	array	Yes	Array of segment objects

Each segment object:

Field	Type	Required	Description
`text`	string	Yes	Segment text content
`start_ms`	int	Yes	Start time in milliseconds
`end_ms`	int	Yes	End time in milliseconds
`speaker`	string	Yes	Speaker identifier
`original_segment_id`	uuid	No	Original segment ID (for translations)

Update Multiple Segments

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

Update Single Segment

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

Field	Type	Required	Description
`speaker_id`	uuid	No	Speaker reference
`text`	string	No	Updated text
`start_ms`	int	No	Updated start time
`end_ms`	int	No	Updated end time

Metadata

Get All Metadata

GET /v1/assets/{asset_id}/metadata

Get Specific Metadata

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

Export Metadata

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

Field	Type	Required	Description
`external_storage_id`	uuid	Yes	Target storage destination

Natural Language Search

POST /v1/nl_search

Field	Type	Required	Description
`query`	string	Yes	Search query (text, or multi-modal with image/audio)
`asset_id`	uuid	No	Scope search to a single asset
`max_results`	int	No	Maximum results (default: 10)

Multi-modal search is supported — combine text queries with image or audio inputs for richer results across speech, visual content, and metadata.

Centers of Interest

Define and retrieve points of interest within your assets, used by auto-reframing and video analysis.

GET    /v1/assets/{asset_id}/centers_of_interest     # List centers of interest
POST   /v1/assets/{asset_id}/centers_of_interest     # Create center of interest
DELETE /v1/assets/{asset_id}/centers_of_interest/{coi_id}  # Delete center of interest

Channels

Create assets from live sources (RTMP, SRT, HLS).

POST   /v1/channels                    # Create channel
GET    /v1/channels                    # List channels
GET    /v1/channels/{channel_id}       # Get channel (includes playback URL)
DELETE /v1/channels/{channel_id}       # Delete channel

Create Asset from Channel

POST /v1/channels/{channel_id}/assets

Field	Type	Required	Description
`external_id`	string	No	Your custom identifier

Publishing

Publish clips to connected social media accounts.

POST /v1/clips/{clip_id}/publish       # Publish a clip
GET  /v1/publish/{job_id}              # Check publishing status

Field	Type	Required	Description
`platform`	string	Yes	Target platform (youtube, instagram, tiktok, linkedin, x, facebook)
`caption`	string	No	Post caption or description
`schedule_at`	datetime	No	Schedule for future publishing (ISO 8601)

Collections

CRUD Operations

POST   /v1/collections                          # Create collection
GET    /v1/collections                           # List collections
GET    /v1/collections/{collection_id}           # Get collection
PATCH  /v1/collections/{collection_id}           # Update collection
DELETE /v1/collections/{collection_id}           # Delete collection

Create requires:

Field	Type	Required	Description
`name`	string	Yes	Collection name
`template_id`	uuid	No	Default template

Manage Collection Assets

POST   /v1/collections/{collection_id}/assets    # Add assets
DELETE /v1/collections/{collection_id}/assets    # Remove assets

Both require:

Field	Type	Required	Description
`asset_ids`	uuid	Yes	Asset IDs to add/remove

Speakers

POST   /v1/assets/{asset_id}/speakers                  # Create speaker
PATCH  /v1/assets/{asset_id}/speakers/{speaker_id}      # Update speaker
DELETE /v1/assets/{asset_id}/speakers/{speaker_id}      # Delete speaker

Create requires:

Field	Type	Required	Description
`name`	string	Yes	Speaker name

Audio Tracks

GET /v1/assets/{asset_id}/audio_tracks                              # List audio tracks
GET /v1/assets/{asset_id}/audio_tracks/{audio_track_id}             # Get audio track
GET /v1/assets/{asset_id}/audio_tracks/{audio_track_id}/download_url # Get download URL

Sound Descriptions

GET    /v1/assets/{asset_id}/sound_descriptions                        # List descriptions
GET    /v1/assets/{asset_id}/sound_descriptions/{description_id}       # Get description
DELETE /v1/assets/{asset_id}/sound_descriptions/{description_id}       # Delete description

Video Analysis

GET /v1/assets/{asset_id}/camera_shoots    # Get camera shoots
GET /v1/assets/{asset_id}/faces            # Get face detections
GET /v1/assets/{asset_id}/autocenter       # Get autocenter data

Video Clips

Create Video Clips

POST /v1/assets/{asset_id}/video_clips

Field	Type	Required	Description
`video_clips`	array	Yes	Array of clip objects

Each clip object:

Field	Type	Description
`start_ms`	int	Clip start time in milliseconds
`end_ms`	int	Clip end time in milliseconds
`start_frame`	int	Clip start frame number
`end_frame`	int	Clip end frame number
`aspect_ratio_x`	int	e.g. 16
`aspect_ratio_y`	int	e.g. 9
`autoframing`	bool	Enable auto-framing
`branding_id`	uuid	Branding to apply
`subtitles_language_id`	uuid	Language for burned-in subtitles
`with_sound_descriptions`	bool	Include sound descriptions

List / Get Clips

GET /v1/assets/{asset_id}/video_clips                  # List clips
GET /v1/assets/{asset_id}/video_clips/{video_id}       # Get clip

Download Clips

POST /v1/assets/{asset_id}/video_clips/download              # Synchronous download
POST /v1/assets/{asset_id}/video_clips/download_async         # Async download job
GET  /v1/assets/{asset_id}/video_clips/download_async/{job_id} # Check download status

Export Clips

POST /v1/assets/{asset_id}/video_clips/{video_clip_id}/export        # Export to storage
POST /v1/assets/{asset_id}/video_clips/{video_clip_id}/async_export  # Async export
GET  /v1/assets/{asset_id}/video_clips/{video_clip_id}/async_export/{job_id} # Check status

External Storage

CRUD Operations

POST   /v1/external_storages                           # Add storage
GET    /v1/external_storages                           # List storages
GET    /v1/external_storages/{external_storage_id}     # Get storage
PATCH  /v1/external_storages/{external_storage_id}     # Update storage
DELETE /v1/external_storages/{external_storage_id}     # Delete storage

Create requires:

Field	Type	Required	Description
`name`	string	Yes	Storage name
`type`	enum	Yes	`aws_s3`, `azure`, `gcp_storage`, or `dummy`
`destination`	object	No	Bucket/container details (varies by type)
`export_path`	string	No	Path template with variables: `{asset_id}`, `{asset_external_id}`, `{video_clip_id}`
`authentication_data`	object	No	Credentials (varies by type)

Destination by type:

Type	Fields
AWS S3	`bucket_name`, `region`
Azure	`blob_url`
GCP Storage	`bucket_name`

Authentication by type:

Type	Fields
AWS S3	`iam_role_arn`
Azure	`sas_token`
GCP Storage	`credentials` (JSON service account)

Admin Endpoints

GET /v1/admin/external_storages                        # List all (admin)
GET /v1/admin/external_storages/{external_storage_id}  # Get (admin)

Templates

POST   /v1/templates                    # Create template
GET    /v1/templates                    # List templates
GET    /v1/templates/{template_id}      # Get template
PATCH  /v1/templates/{template_id}      # Update template
DELETE /v1/templates/{template_id}      # Delete template

Create/update fields:

Field	Type	Required	Description
`name`	string	Yes	Template name
`domain_dictionary_ids`	uuid	No	Associated dictionaries
`blacklist_ids`	uuid	No	Associated blacklists
`whitelist_ids`	uuid	No	Associated whitelists
`translation_language_ids`	uuid	No	Auto-translate languages
`voice_over_language_ids`	uuid	No	Auto voice-over languages
`enabled_ocr`	bool	No	Enable OCR (default: false)
`voice_over_config`	object	No	`clone_voice` (bool), `mute_original_voice` (bool)

Brandings

Core Brandings

POST   /v1/brandings                    # Create branding
GET    /v1/brandings                    # List brandings
GET    /v1/brandings/{branding_id}      # Get branding
PATCH  /v1/brandings/{branding_id}      # Update branding
DELETE /v1/brandings/{branding_id}      # Delete branding

Branding Variants

Each branding can have variants for different aspect ratios.

POST   /v1/brandings/{branding_id}/variants                  # Add variant
GET    /v1/brandings/{branding_id}/variants                  # List variants
GET    /v1/brandings/{branding_id}/variants/{variant_id}     # Get variant
PATCH  /v1/brandings/{branding_id}/variants/{variant_id}     # Update variant
DELETE /v1/brandings/{branding_id}/variants/{variant_id}     # Delete variant

Field	Type	Required	Description
`aspect_ratio`	enum	Yes	`9:16`, `1:1`, `4:5`, `16:9`, `4:3`, or `3:4`
`overlay_id`	uuid	No	Overlay to apply
`intro_id`	uuid	No	Intro clip
`outro_id`	uuid	No	Outro clip

Branding Overlays

POST   /v1/branding_overlays                              # Create overlay
GET    /v1/branding_overlays                              # List overlays
GET    /v1/branding_overlays/{overlay_id}                 # Get overlay
PATCH  /v1/branding_overlays/{overlay_id}                 # Update overlay
DELETE /v1/branding_overlays/{overlay_id}                 # Delete overlay
POST   /v1/branding_overlays/{overlay_id}/start_upload    # Start upload
POST   /v1/branding_overlays/{overlay_id}/finish_upload   # Finish upload
GET    /v1/branding_overlays/{overlay_id}/upload_jobs/{job_id} # Check upload status

Branding Clips

POST   /v1/branding_clips                              # Create clip
GET    /v1/branding_clips                              # List clips
GET    /v1/branding_clips/{clip_id}                    # Get clip
PATCH  /v1/branding_clips/{clip_id}                    # Update clip
DELETE /v1/branding_clips/{clip_id}                    # Delete clip
POST   /v1/branding_clips/{clip_id}/start_upload       # Start upload
POST   /v1/branding_clips/{clip_id}/finish_upload      # Finish upload
GET    /v1/branding_clips/{clip_id}/upload_jobs/{job_id} # Check upload status

Branding Subtitle Styles

POST   /v1/branding_subtitle_styles                    # Create style
GET    /v1/branding_subtitle_styles                    # List styles
GET    /v1/branding_subtitle_styles/{style_id}         # Get style
PATCH  /v1/branding_subtitle_styles/{style_id}         # Update style
DELETE /v1/branding_subtitle_styles/{style_id}         # Delete style

Field	Type	Default	Description
`name`	string	—	Style name (required)
`font_family`	string	—	Font family (required)
`text_color`	hex	—	Text color e.g. `#050B07` (required)
`font_size_px`	int	26	Font size in pixels
`font_weight`	int	600	Font weight
`line_height`	float	1.2	Line height
`vertical_position_pct`	float	0.1	Vertical position (% of video height)
`shadow_blur`	float	0.0	Shadow blur radius
`shadow_color`	hex	—	Shadow color
`shadow_opacity_pct`	float	1	Shadow opacity
`shadow_offset_x_px`	int	1	Shadow X offset
`shadow_offset_y_px`	int	1	Shadow Y offset
`background_color`	hex	—	Background color
`background_opacity`	float	0.0	Background opacity
`stroke_color`	hex	`#000000`	Stroke color
`stroke_thickness_px`	int	0	Stroke thickness

Word Lists

Blacklists

Words to filter from transcriptions.

POST   /v1/blacklists                      # Create blacklist
GET    /v1/blacklists                      # List blacklists
GET    /v1/blacklists/{blacklist_id}       # Get blacklist
PATCH  /v1/blacklists/{blacklist_id}       # Update blacklist
DELETE /v1/blacklists/{blacklist_id}       # Delete blacklist

Field	Type	Required	Description
`name`	string	Yes	Blacklist name
`words`	string	Yes	Words to filter
`language_id`	uuid	Yes	Language reference
`template_id`	uuid	No	Associated template

Whitelists

Words to preserve in transcriptions.

POST   /v1/whitelists                      # Create whitelist
GET    /v1/whitelists                      # List whitelists
GET    /v1/whitelists/{whitelist_id}       # Get whitelist
PATCH  /v1/whitelists/{whitelist_id}       # Update whitelist
DELETE /v1/whitelists/{whitelist_id}       # Delete whitelist

Field	Type	Required	Description
`name`	string	Yes	Whitelist name
`words`	string	Yes	Words to preserve
`template_id`	uuid	No	Associated template

Dictionaries

Term expansion maps for transcription accuracy.

POST   /v1/dictionaries                      # Create dictionary
GET    /v1/dictionaries                      # List dictionaries
GET    /v1/dictionaries/{dictionary_id}      # Get dictionary
PATCH  /v1/dictionaries/{dictionary_id}      # Update dictionary
DELETE /v1/dictionaries/{dictionary_id}      # Delete dictionary

Field	Type	Required	Description
`name`	string	Yes	Dictionary name
`dictionary`	object	Yes	Key-value map, e.g. `{"AI": ["Artificial Intelligence"]}`
`template_id`	uuid	No	Associated template

Languages

GET /v1/languages                  # List all languages
GET /v1/languages/{language_id}    # Get language details

Filter Views

POST   /v1/views                    # Create view
GET    /v1/views                    # List views
GET    /v1/views/{view_id}          # Get view
PATCH  /v1/views/{view_id}          # Update view
DELETE /v1/views/{view_id}          # Delete view

Field	Type	Required	Description
`name`	string	Yes	View name
`filter_params`	array	Yes	Array of filter conditions (min 1)

Usage & Billing

GET /v1/usages/current_month    # Current month usage
GET /v1/usages/historical       # Historical usage data

MCP Server

Connect AI agents for automated workflows.

Links & Resources

Official channels, media kit, contact.