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
`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
`asset_id`	uuid	No	Scope search to a single asset
`max_results`	int	No	Maximum results (default: 10)

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.