Skip to content
Guide · API v1

ClipMatrix documentation

From your first recording to a finished clip. Start in the studio or build your workflow with the public API.

Your first clip in the studio

You do not need the API for everyday editing. Open the ClipMatrix studio, sign in and create a project.

  1. Add your recording. Paste a video link or upload a file. Wait for the import and source checks to finish.
  2. Start processing. Choose the language and selection settings. ClipMatrix prepares candidate clips; the number depends on the source material.
  3. Review the selection. Check the opening, ending and context of each clip. A review label means you should inspect it before publishing.
  4. Refine it in the editor. Adjust the boundaries, aspect ratio, framing and captions. Check names and specialist terms.
  5. Render and download. After editing, wait for the current version to finish rendering. Watch the exported file with sound before publishing.

Source minutes, storage and other limits are available in your account and on the plans page. To automate this workflow, continue with API access.

Access and API tokens

Base URL: https://clipmatrix.app/api/v1. Personal API tokens are available on active Pro and Max plans. Create a token in account settings, give it a name and choose an expiry. The secret is shown once.

Send the token in the Authorization: Bearer … header. Keep it in a server environment variable; do not include it in browser code, a repository or public logs. This first request checks access and returns the account, quota and style catalog.

export CM_URL='https://clipmatrix.app'
# Bash: enter your token without displaying it.
read -r -s CM_TOKEN
export CM_TOKEN

curl --fail-with-body "$CM_URL/api/v1/account" \
  -H "Authorization: Bearer $CM_TOKEN"

Examples use Bash, curl and uuidgen. Replace YOUR_… values with your own URLs and IDs. Do not paste the token directly into commands.

An account can have up to 20 active tokens. An expired or revoked token returns 401; an account without an eligible active plan receives 403 api_plan_required. The API can access only projects owned by the token holder.

Import a recording

POST /projects creates a project and starts importing a video link. A 202 response means the request was accepted: the source may still be downloading. Save the returned id.

# Create once; keep this key for retries of the same import.
CM_IMPORT_KEY=$(uuidgen)

curl --fail-with-body -X POST "$CM_URL/api/v1/projects" \
  -H "Authorization: Bearer $CM_TOKEN" \
  -H "Idempotency-Key: $CM_IMPORT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.youtube.com/watch?v=YOUR_VIDEO","language":"auto"}'

url is required. An optional title accepts 1–180 characters; language accepts auto, ru or en. For a local recording, use file upload instead.

# Replace this with the id returned by POST /projects.
CM_PROJECT_ID='YOUR_PROJECT_ID'

curl --fail-with-body "$CM_URL/api/v1/projects/$CM_PROJECT_ID" \
  -H "Authorization: Bearer $CM_TOKEN"

Poll the project approximately every 3 seconds. Wait while job.status is queued or running. Stop the sequence and inspect the error on error or cancelled. After a successful import, start processing explicitly.

Creating a project does not select clips or deduct processing minutes by itself.

Process and select clips

POST /projects/{pid}/process starts clip selection and uses source minutes under the account’s plan. Call it after the source is ready. Keep the request key so a connection failure can be retried safely.

CM_PROCESS_KEY=$(uuidgen)

curl --fail-with-body -X POST \
  "$CM_URL/api/v1/projects/$CM_PROJECT_ID/process" \
  -H "Authorization: Bearer $CM_TOKEN" \
  -H "Idempotency-Key: $CM_PROCESS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"language":"auto","count":3,"target_seconds":60}'
ParameterValue
languageauto, ru or en.
count1–200. An upper bound on candidate count, not a guarantee that this many clips will be found.
target_seconds20–180. The target duration used for selection.

Monitor GET /projects/{pid}. Once processing finishes, retrieve the clips:

curl --fail-with-body \
  "$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips?offset=0&limit=20" \
  -H "Authorization: Bearer $CM_TOKEN"

The response contains clips, total, offset and limit. A page can contain up to 50 clips. An empty list is valid: the recording may not yield suitable segments.

editorial_status: ready means selection did not flag the clip for additional review; review calls for a manual check. Read editorial_note. These fields do not mean an MP4 exists: file readiness is tracked separately by render.status.

Render, MP4 and subtitles

Start rendering a selected clip. A 202 response confirms acceptance, not file readiness. If the current version is already rendered, it is not rendered again.

# Use a clip id returned by the clips endpoint.
CM_CLIP_ID='YOUR_CLIP_ID'
CM_RENDER_KEY=$(uuidgen)

curl --fail-with-body -X POST \
  "$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID/render" \
  -H "Authorization: Bearer $CM_TOKEN" \
  -H "Idempotency-Key: $CM_RENDER_KEY" \
  -H 'Content-Type: application/json' -d '{}'

curl --fail-with-body \
  "$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID" \
  -H "Authorization: Bearer $CM_TOKEN"

Wait for render.status: ready in the clip response. To render several clips, use POST /projects/{pid}/clips/render with {"clip_ids":["id1","id2"]}; up to 200 IDs are accepted. Export does not use source minutes, but normal render-attempt limits apply.

The finished file

The final POST …/download returns download_url, the authentication method and link expiry. It also applies a one-time branding reward when the clip qualifies under the service rules.

curl --fail-with-body -X POST \
  "$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID/download" \
  -H "Authorization: Bearer $CM_TOKEN" \
  -H 'Content-Type: application/json' -d '{}'

curl --fail-with-body \
  "$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID/subtitles?format=srt" \
  -H "Authorization: Bearer $CM_TOKEN" -o clip.srt

For authentication: signed_url, download download_url with a plain GET and no Authorization header. The link lasts up to 300 seconds; do not use it as a permanent file address. For authentication: bearer, the URL is a protected API route and requires the token.

Subtitles support srt, vtt and txt and reflect the finished export, including its edits. Their API URLs require Bearer authentication. A subtitle-specific error can occur while the MP4 remains available.

Full source: GET /projects/{pid}/source. It returns a temporary URL lasting up to 1 hour. If the original is not ready yet, the server responds with 409 source_not_ready.

Text, style and framing

PATCH /projects/{pid}/clips/{cid} changes the supplied fields on one clip. Omitted settings are preserved. A title accepts up to 160 characters, a description up to 300 and hashtags up to 5 entries such as #ClipMatrix.

curl --fail-with-body -X PATCH \
  "$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID" \
  -H "Authorization: Bearer $CM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"description":"A useful moment from the conversation","hashtags":["#ClipMatrix"]}'

Description and hashtag changes update publication text without new selection or rendering. Changes to the title, boundaries, style or framing can trigger a new render. start and end are absolute seconds in the source recording.

Aspect ratio and captions

aspect and caption_preset are accepted both when processing a project and when patching a clip. Use 9:16, 1:1 or 16:9; read style IDs from caption_presets in GET /account. The full captions object is described in OpenAPI.

Framing without overwriting edits

The clip GET response includes framing.version. Send this version with camera, scenes and/or speaker_zoom. Send the complete scenes array; scene times are measured from the start of the source. On 409 edit_conflict, fetch the latest data before retrying.

Automatic speaker tracking uses POST …/clips/{cid}/speaker. Wait for speaker_analysis.status: ready before requesting the render. An earlier attempt may return 409 speaker_analysis_required.

If an edit was saved but render admission failed, resolve the cause and call render. You do not need to resend the entire PATCH.

Multipart file upload

Use multipart upload for a local file. First request GET /uploads/config to check availability and upload settings. Use the sizes and URLs returned by the server throughout the upload.

  1. Create an upload with POST /uploads. Supply the filename, actual file size and a fresh UUID in idempotency_key. Keep the same key and parameters when retrying that upload.
{
  "filename": "recording.mp4",
  "size_bytes": 104857600,
  "idempotency_key": "example-upload-key",
  "language": "auto"
}
  1. Save the upload id and project_id. The response also includes part_size_bytes, parts_count, parallel_parts and expires_at.
  2. Request part URLs with POST /uploads/{id}/parts and {"part_numbers":[1,2,3]}. A request accepts up to 12 part numbers.
  3. PUT each part to its returned URL. Respect offset_bytes, size_bytes, the returned headers and Content-Length. Do not send your ClipMatrix token to storage. Upload no more than 3 parts simultaneously and respect parallel_parts.
  4. After all parts are transferred, call POST /uploads/{id}/complete with {}. The 202 response starts media validation.
  5. Wait for state: ready in GET /uploads/{id}, then call process on the project.

The example size is 100 MiB: replace it with your file’s actual size and generate your own UUID. GET /uploads/{id} also lists uploaded parts so a transfer can resume. DELETE /uploads/{id} cancels an unfinished upload.

Transferring the file does not use processing minutes. File size, duration, storage and available-minute checks follow the account’s limits.

Statuses and safe retries

The default rate limit is 60 requests per minute per token. On 429 rate_limited, respect Retry-After. Public webhooks are not available in API v1; poll approximately every 3 seconds while accounting for the combined request rate of all jobs.

render.statusClient action
noneNo current ready render exists. Request rendering when needed.
queuedThe clip is queued. Continue polling.
runningThis clip is rendering. Wait for completion.
readyThe current file is ready to download.
failedRead render.error and resolve the cause before retrying.

Project state and clip state differ: a finished clip can remain available when another part of a batch fails. New integrations should use render; build_status remains for compatibility. Unknown progress can be null.

Idempotency-Key

This header is supported for project creation, processing and single or batch rendering. Create one key per intentional action. Repeating the same method, path and JSON with the same key within 24 hours returns the original response without another operation. Use GET for fresh status.

A key contains 1–128 printable ASCII characters without spaces, such as a UUID. Reusing it for a different request returns 409 idempotency_conflict. An intentional new processing run needs a new key and uses minutes. For other POST/PATCH requests, inspect the state after a network failure before retrying.

Errors and recovery

Use the HTTP status and machine-readable error.code rather than matching the message text. The general response shape is:

{
  "error": {
    "code": "edit_conflict",
    "message": "…",
    "details": {}
  },
  "detail": "…"
}
ResponseWhat to check
401 invalid_api_tokenCheck the header, token expiry and revocation. Create a new token if needed.
403 api_plan_requiredCheck that an API-enabled plan is active.
404Check IDs and project ownership: another account’s resources are not disclosed.
409 render_requiredRender the current clip version and wait for ready.
409 edit_conflictFetch the latest framing version and reconcile the edit.
409 speaker_analysis_requiredWait for speaker analysis before rendering.
422 validation_errorCheck field names, types and allowed ranges. Unknown fields are rejected.
429 rate_limitedReduce request frequency and respect Retry-After.
429 quota_exceededInspect the account quota; repeated requests will not restore it.

Background job errors appear in project state; render errors appear in render.error. Keep the error code, project ID and clip ID when contacting support. Do not send your token or a signed file URL.

Endpoint reference

All paths below use the /api/v1 prefix. Requests with a body use JSON and Content-Type: application/json. Retrieve the complete parameter schema with an authenticated GET /api/v1/openapi.json. The service-wide schema is available in OpenAPI JSON ↗.

Method and pathPurpose
GET /accountAccount, quota and style catalog.
POST /tokensCreate a token with name and expires_in_days from 1 to 365.
GET /tokensList tokens without their secrets.
DELETE /tokens/{id}Revoke your token.
POST /projectsImport a video link.
GET /projects/{pid}Project and job status.
POST /projects/{pid}/processStart clip selection.
GET /projects/{pid}/clipsPaginated clip list.
GET /projects/{pid}/clips/{cid}Clip, framing and render status.
PATCH /projects/{pid}/clips/{cid}Edit text, boundaries and styling.
POST /projects/{pid}/clips/{cid}/renderRender one clip.
POST /projects/{pid}/clips/renderRender a batch of selected clips.
POST /projects/{pid}/clips/{cid}/downloadGet the final download URL.
GET /projects/{pid}/clips/{cid}/subtitlesSubtitles from the finished export.
GET /projects/{pid}/sourceTemporary URL for the full source.
GET /branding-assetsBranding catalog available to the account; inspect enabled.

Catalogs reflect feature availability for the account. Read them rather than hard-coding unknown IDs, and handle unavailable options. The multipart upload section covers the complete file-transfer sequence.

NEXT STEP

Try it with your video.

Start free ↗