API & Developers

REST API

Every Cap Infra endpoint, field and error code, for video hosting and speech to text

The Cap Infra API does two things for your product. It hosts video: you upload a file, Cap encodes it, and you play it back as adaptive HLS or MP4, or with the hosted player. It turns speech into text: you send an audio or video file to Transcripts and get the text back, with timings.

New to the API? Get Started goes from a new app to a video playing on your page, with examples for the browser, Node and Python. This page is the reference.

There are two APIs:

  • REST API (/api/developer/v1) -- Server-side: create uploads, manage videos, transcribe audio and read usage, authenticated with secret keys (csk_).
  • SDK API (/api/developer/sdk/v1) -- Browser-side: upload a video's file, authenticated with an upload token (cut_) that your server creates for that one video.

These keys do not authenticate the Cap CLI. For CLI keys (cap_cli_), used with CAP_API_KEY in headless environments, see Set Up Your Agent.

A video goes through four steps:

  1. Create Upload from your server with the secret key. It returns an upload token.
  2. Upload the file from the browser with that token, using Multipart Upload.
  3. Poll Get Video Status with the secret key until status is ready or errored.
  4. Play it. See Play a Video.

Authentication

Getting Your API Keys

API keys are managed in Cap Infra, not the general Settings page.

  1. Go to cap.so/dashboard/infra.
  2. Create an app and give it a name and environment (development or production).
  3. Two keys are generated for each app:
    • Secret key (csk_...) -- Must be kept private. Used with the REST API, including to create uploads.
    • Public key (cpk_...) -- Cannot create or upload videos. Browsers upload with an upload token instead.
  4. Store both keys securely. Generating new keys on the API keys page replaces the previous keys and revokes the upload tokens the previous secret key created.

Using Your Keys

Include the appropriate key in the Authorization header as a Bearer token:

Authorization: Bearer csk_your_secret_key_here

The SDK API takes an upload token instead. Your server gets one from Create Upload and hands it to the browser:

Authorization: Bearer cut_your_upload_token_here

An upload token works for one video and for a limited time, so it is safe to send to the browser. A public key on its own cannot start an upload or call the REST API: both answer 403 with code public_key_not_allowed. A REST request with no Authorization header answers 401 with code invalid_secret_key and the message Missing secret key.

Keep your secret key private. Never expose it in client-side code, commit it to version control, or share it publicly. The REST API sends no CORS headers, so a page cannot call it. Call it from your server, and give the page an upload token for the SDK API.

OpenAPI

A machine-readable OpenAPI 3.1 description of both APIs is published at cap.so/openapi.json. Import it into an API client, generate a typed client, or give it to an agent as tool definitions.

Base URL

REST API (secret key):

https://cap.so/api/developer/v1

SDK API (upload token):

https://cap.so/api/developer/sdk/v1

If you are self-hosting Cap, replace cap.so with your custom domain.

Error Handling

Every error is a JSON object with an error string, a stable code, a hint that says what to change, and a link to these docs. message holds the same text as error. Switch on code, not on the text. Every response on cap.so carries an X-Request-Id header: quote it when you contact support about a call.

{
  "error": "Invalid secret key",
  "code": "invalid_secret_key",
  "message": "Invalid secret key",
  "hint": "Send Authorization: Bearer csk_... with a secret key from https://cap.so/dashboard/infra.",
  "docs": "https://cap.so/docs/api/rest-api"
}

A request body that fails validation returns 400 with the code invalid_request and an issues array that names each failing field:

{
  "error": "Invalid request: maxResolutionTier: Invalid option: expected one of \"1080p\"|\"1440p\"|\"2160p\"",
  "code": "invalid_request",
  "message": "Invalid request: maxResolutionTier: Invalid option: expected one of \"1080p\"|\"1440p\"|\"2160p\"",
  "hint": "Fix the fields listed in issues, then send the request again.",
  "docs": "https://cap.so/docs/api/rest-api",
  "issues": [
    {
      "code": "invalid_value",
      "values": ["1080p", "1440p", "2160p"],
      "path": ["maxResolutionTier"],
      "message": "Invalid option: expected one of \"1080p\"|\"1440p\"|\"2160p\""
    }
  ]
}

A 402 from Create Upload, Complete Upload or Create Transcript has a hint that links the app's own Billing page, where credit is added. The upload 402 also carries the balance fields shown under Create Upload.

Send request bodies as JSON with the header Content-Type: application/json. Malformed JSON returns 400 with the code invalid_json, and a body sent with any other content type returns 415 with the code unsupported_media_type.

Status CodeDescription
200Success
400Bad request. The code says what was wrong, for example invalid_request, invalid_json, invalid_limit or unknown_parameter
401Unauthorized. The API key or upload token is missing, invalid, revoked or expired
402Payment required. The app is out of credit, its balance does not cover the storage an upload needs, or it is below the minimum to start a transcript
403Forbidden. A public key was sent where a secret key or upload token is required (public_key_not_allowed). On the SDK API, the Origin differs from the upload token's corsOrigin (origin_not_allowed) or the body names another video (video_mismatch). Elsewhere, the account cannot use this feature yet
404Not found. The video, transcript or multipart upload does not exist (video_not_found, transcript_not_found, upload_not_found for an uploadId), or no route matches the path (not_found)
405Method not allowed. The path exists but not with this method (method_not_allowed). The Allow header lists the methods it takes
409Conflict with the current state, for example an upload that already completed, or a transcript started before its file was uploaded (upload_not_found). The code says which
415Unsupported media type. The body was not sent as application/json
429Too many requests. See Rate Limits
500Internal server error (internal_error). Retry with backoff
503Transcription is temporarily unavailable. Retry later

A 4xx response will not succeed if the same request is sent again, with two exceptions that say to wait and repeat it: 429, and 409 with the code completion_in_progress from complete. The same 409 from abort is different: do not repeat the abort (see Abort Upload).

Rate Limits

A secret key allows 300 requests per minute, counted across every REST endpoint. All the keys of one account together allow 1,200 requests per minute, so an account with several apps shares that total between them. An upload token allows 1,200 requests per minute, counted across the SDK endpoints. Playback URLs need no key and are not counted.

Every response to an accepted key or upload token carries three headers:

HeaderMeaning
X-RateLimit-LimitRequests the key or upload token may make per minute
X-RateLimit-RemainingRequests left this minute, as counted by the server that answered. 0 on a 429
X-RateLimit-ResetSeconds until that count starts again. On a 429, the same value as Retry-After

Past the limit the API answers 429 with the code rate_limited and a Retry-After header in seconds, never more than 60. A 429 is authoritative: wait for Retry-After seconds, then send the request again.

X-RateLimit-Remaining and X-RateLimit-Reset are a guide. Requests can be answered by more than one server and each reports what it has counted itself, so X-RateLimit-Remaining can read higher than what is left and can differ from one response to the next. Use it to slow down early, not to decide that the next request will succeed.

A request whose key or upload token is not accepted is answered 401 and spends none of a key's budget. Sending the same refused key again is answered 401 at once, and a valid key from the same address keeps working. An address that sends many different refused keys or tokens in a minute is answered 429 until the minute is over.

Each upload token has its own count, separate from your secret key's and from every other upload. Each uploaded part spends one presign request from it, so one upload can sign twenty parts a second.

Pagination

List endpoints support pagination via query parameters:

ParameterTypeDefaultRangeDescription
limitinteger501 to 100Number of items to return
offsetinteger00 and upNumber of items to skip

Lists are strict about their query string. A limit or offset that is not a whole number in range returns 400 with the code invalid_limit or invalid_offset, and a query parameter the list does not know returns 400 with the code unknown_parameter. Parameter names are case-sensitive. Nothing is clamped or ignored, so a mistyped filter never returns an unfiltered list.

Every list returns pagination next to data, with the limit and offset it used and hasMore. To paginate, increment offset by limit until hasMore is false.


REST API Endpoints

All REST API endpoints require a secret key (csk_) in the Authorization header.

Create Upload

Create a video and an upload token for it. Call this from your server, then give the token to the browser that uploads the file.

POST /api/developer/v1/uploads

Request body (JSON):

FieldTypeRequiredDescription
namestringNoVideo name, up to 255 characters (defaults to "Untitled")
userIdstringNoYour external user ID for filtering, up to 255 characters. Videos return it as externalUserId
maxResolutionTierstringNoHighest resolution to encode: 1080p (default), 1440p or 2160p
metadataobjectNoYour own JSON object to store with the video, under 8KB
corsOriginstringNoExact origin of the page that uploads, such as https://app.example.com, with no path or trailing slash
timeoutSecondsintegerNoHow long the token works, in seconds from 60 to 86400. Defaults to 3600
maxBytesintegerNoLargest file the token may upload, in bytes, from 1 to 36000000000. Leave it out for no cap beyond the 36 GB limit

The body is optional. A request with no body creates an upload with the defaults.

Supported formats. Cap Infra accepts MP4, MOV, MKV and WebM files with H.264, HEVC, VP8, VP9, AV1, ProRes, MPEG-4 or Motion JPEG video. A video in another format may fail to process, and its errorReason then says why.

Send an Idempotency-Key header so a retried request returns the same video with a new upload token instead of creating a second one. The key follows the same rules as for transcripts. A repeat must send the same name, userId, maxResolutionTier and metadata, otherwise it is refused with 409 idempotency_conflict and the message names the field that differs. corsOrigin, timeoutSeconds and maxBytes only shape the new token, so they may change. A key for a video that was deleted is refused with 409 idempotency_conflict, and a repeat after the upload completed answers 409 upload_already_completed.

A field this list does not have returns 400 with the code invalid_request, and the error names the field. Field names are case-sensitive, so user_id in place of userId is refused instead of creating a video with no user:

{
  "error": "Invalid request: Unrecognized key: \"user_id\"",
  "code": "invalid_request",
  "message": "Invalid request: Unrecognized key: \"user_id\"",
  "hint": "This request accepts name, userId, maxResolutionTier, metadata, corsOrigin, timeoutSeconds, maxBytes. Field names are case-sensitive.",
  "docs": "https://cap.so/docs/api/rest-api",
  "issues": [
    { "code": "unrecognized_keys", "keys": ["user_id"], "path": [], "message": "Unrecognized key: \"user_id\"" }
  ]
}

Example request:

curl -X POST https://cap.so/api/developer/v1/uploads \
  -H "Authorization: Bearer csk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "User Recording", "userId": "user_42", "corsOrigin": "https://app.example.com"}'

Example response:

{
  "data": {
    "id": "abc123def456",
    "videoId": "abc123def456",
    "token": "cut_eyJ2IjoxLCJhcHAiOiIuLi4ifQ.Jm2c...",
    "expiresAt": "2026-03-10T15:30:00.000Z",
    "corsOrigin": "https://app.example.com",
    "maxBytes": null,
    "status": "uploading",
    "uploadUrl": "https://cap.so/api/developer/sdk/v1/upload/multipart",
    "playbackId": "Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
    "shareUrl": "https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
    "embedUrl": "https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/embed"
  }
}

Each video takes one upload, so id equals videoId. shareUrl and embedUrl are a hosted player for the video. See Share and Embed. To build your own player, see Play a Video.

The token is the only credential the SDK API accepts, and it is returned once:

  • It uploads this video and no other.
  • It works until expiresAt. Raise timeoutSeconds for large files on slow connections. If it expires before the upload completes, renew it and continue the same upload.
  • It stops working when the upload completes or the video is deleted.
  • It stops working when the secret key that created it is revoked. Renew it with the new secret key to continue the same upload.

maxBytes caps the file a token can upload. Initiate Upload refuses a declared contentLength over the cap before any byte is sent, and Complete Upload measures the bytes in storage and refuses an upload over the cap, whatever sizes the request claims. Both answer 400 with the code file_too_large. Without maxBytes the only limit is the 36 GB one. The cap also limits the part numbers a token can sign, see Get Presigned Part URL.

A video whose upload is never completed stays in the uploading status and counts in uploadingVideos until you delete it with Delete Video.

corsOrigin is a convenience for browser uploads. When it is set, the SDK API refuses a request whose Origin header is anything else. A script can send any Origin it likes, so the token is what protects the upload, not the origin. Leave corsOrigin out to upload from a server or a native app.

Creating an upload is free. It returns 402 if the app is out of credit, or if its balance does not cover the first month of storage for every upload of the app still encoding plus 7 days for the videos past their first month. Here one 60 minute video billed at 4K is still encoding. The 402 body says how much is needed:

{
  "error": "Insufficient credits",
  "code": "insufficient_credits",
  "message": "Not enough credit to upload. Uploading needs $0.16800, enough for the first month of storage for each video being uploaded or encoded. The balance is $0.05, so add at least $0.11800.",
  "hint": "Add credits to this app at https://cap.so/dashboard/infra/app_789/billing, then retry.",
  "docs": "https://cap.so/docs/api/rest-api",
  "standing": "active",
  "pausesAt": null,
  "balanceMicroCredits": 5000,
  "requiredMicroCredits": 16800,
  "shortfallMicroCredits": 11800
}

code is insufficient_credits, out_of_credit (the app is in grace or paused) or no_account.

Renew Upload Token

Get a new token for a video whose upload has not completed. Use it when an upload outlives its token: the file does not have to be sent again.

POST /api/developer/v1/uploads/:id/token

:id is the videoId from Create Upload.

Request body (JSON):

FieldTypeRequiredDescription
corsOriginstringNoSame as Create Upload
timeoutSecondsintegerNoSame as Create Upload. Defaults to 3600
maxBytesintegerNoSame as Create Upload

The body is optional. The new token carries only the options sent here, so send corsOrigin and maxBytes again if the first token had them. Any other field returns 400.

Example request:

curl -X POST https://cap.so/api/developer/v1/uploads/abc123def456/token \
  -H "Authorization: Bearer csk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{"corsOrigin": "https://app.example.com"}'

Example response:

{
  "data": {
    "id": "abc123def456",
    "videoId": "abc123def456",
    "token": "cut_eyJ2IjoxLCJhcHAiOiIuLi4ifQ.Qx7p...",
    "expiresAt": "2026-03-10T16:45:00.000Z",
    "corsOrigin": "https://app.example.com",
    "maxBytes": null,
    "status": "uploading",
    "uploadUrl": "https://cap.so/api/developer/sdk/v1/upload/multipart"
  }
}

When a token expires mid-upload. Every SDK API call then answers 401 with the code upload_token_expired. Parts already in storage are kept, and a PUT to a presigned URL you already hold still works until that URL expires. To finish the upload:

  1. The browser keeps its uploadId and the ETag of every part it has uploaded, and asks your server for a new token.
  2. Your server checks the user still owns the video, calls Renew Upload Token and returns the new token.
  3. The browser signs the parts it has not uploaded with the new token and the same uploadId, uploads them, then calls Complete Upload with every part.

If the page was reloaded and lost its uploadId, call Initiate Upload with the new token. It returns the same uploadId when the upload was opened in the last 6 hours. It cannot list the parts already uploaded, so a page that has also lost its ETags sends the parts again.

An upload left open is discarded a day after it was opened. After that, Complete Upload returns 404 with the code upload_not_found: call Initiate Upload again and send the file again.

Renewing does not cancel earlier tokens. Each works until its own expiresAt.

When the secret key is regenerated mid-upload. Tokens created with the previous secret key answer 401 with the code invalid_upload_token, and the hint says the key was rotated. Renew the token with the new secret key and finish the upload the same way.

StatuscodeMeaning
404video_not_foundThe video was deleted, or does not belong to this app
409upload_already_completedThe upload already completed. There is nothing left to upload

Import from a URL

Create a video from a file at a public https URL. Cap downloads the file itself, then encodes it exactly as it would an upload, so there is nothing to upload from your side.

POST /api/developer/v1/videos

Request body (JSON):

FieldTypeRequiredDescription
urlstringYesPublic https URL of the video file itself, up to 2,048 characters. A page that plays the video is not the file
namestringNoVideo name, up to 255 characters (defaults to "Untitled")
userIdstringNoYour external user ID for filtering, up to 255 characters. Videos return it as externalUserId
maxResolutionTierstringNoHighest resolution to encode: 1080p (default), 1440p or 2160p
metadataobjectNoYour own JSON object to store with the video, under 8KB

Example request:

curl -X POST https://cap.so/api/developer/v1/videos \
  -H "Authorization: Bearer csk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-product-tour-1" \
  -d '{"url": "https://cdn.example.com/videos/product-tour.mp4", "name": "Product tour"}'

The answer is the video, in the status uploading while the file downloads, with an import object:

{
  "data": {
    "id": "abc123def456",
    "status": "uploading",
    "name": "Product tour",
    "playbackId": "Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
    "shareUrl": "https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
    "embedUrl": "https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/embed",
    "import": {
      "sourceUrl": "https://cdn.example.com/videos/product-tour.mp4",
      "state": "downloading",
      "errorCode": null
    }
  }
}

The example leaves out the other video fields. Then poll Get Video Status every 3 seconds, or wait for the video.ready webhook. import.state is downloading, then complete once the file is stored and encoding starts, or failed.

Before it answers, Cap opens the URL and reads the first bytes, so the common mistakes come back on the request itself:

StatuscodeMeaning
400url_not_allowedThe URL is not public https on the default port, has a username or password, or points to a private, loopback, link-local or cloud metadata address, directly, through its DNS name or through a redirect
422url_unreachableThe URL answered with an error status, sent nothing, redirected more than 3 times or refused the connection
422unsupported_formatThe URL is a web page, a playlist, an image, a document or audio, not a video file
413too_largeThe file declares a size over the 36 GB limit
422timeoutThe host did not answer in time
402insufficient_creditsThe balance does not cover the file at its declared size, as for an upload
429too_many_importsThe app already has 2 imports downloading. Wait for Retry-After seconds
429import_rate_limitedThis key started 30 imports in the last hour. Retry-After says when the next one is allowed

The whole file must download within 10 minutes, so the host has to keep up a steady speed: a 4.7 GB file needs about 8 MB/s from start to finish. The download also stops if the host sends nothing for 30 seconds, and a file that turns out larger than the limit while it streams is stopped too. If the download fails after the request answered, the video moves to errored, errorReason starts with Import failed:, and import.errorCode gives the code. A download that runs out of time ends with download_timeout. So does a download that stops without reporting back, within 35 minutes of the request. Use Create Upload for files on your own machine, for large files, and for hosts that can't send the file in 10 minutes.

Billing is the same as for an upload: the video is admitted again on its measured length before it is encoded, and storage is billed once it is ready. A failed import costs nothing.

Send an Idempotency-Key header so a retried request returns the same video instead of downloading the file twice. A repeat must send the same url, name, userId, maxResolutionTier and metadata, otherwise it is refused with 409 idempotency_conflict.

List Videos

Retrieve videos created by your app, newest first. Deleted videos are not returned. Videos created in the same second always come back in the same order.

GET /api/developer/v1/videos

Query parameters:

ParameterTypeRequiredDescription
userIdstringNoOnly return videos created with this userId. Videos return it as externalUserId
externalUserIdstringNoAnother name for the userId filter. Sending both with different values returns 400 with the code conflicting_parameters
limitintegerNoNumber of results, 1 to 100 (default 50)
offsetintegerNoNumber of results to skip (default 0)

Any other query parameter returns 400. See Pagination.

The userId filter matches the exact value: alice, Alice and àlice are three different users. Spaces around the value are ignored. A filter that is sent always filters: a userId or externalUserId that is present but empty, or only spaces, returns 400 with the code invalid_user_id and never the whole list, and a parameter sent more than once returns 400 with the code repeated_parameter. Leave the parameter out to list every user's videos.

Example request:

curl "https://cap.so/api/developer/v1/videos?limit=10" \
  -H "Authorization: Bearer csk_your_secret_key_here"

Example response:

Each item is the full video object, the same one Get Video returns. This example holds a ready video and one that was created and is still waiting for its file.

{
  "data": [
    {
      "id": "abc123def456",
      "appId": "app_789",
      "externalUserId": "user_42",
      "name": "Product Demo",
      "duration": 124.5,
      "durationSeconds": 124.5,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "transcriptionStatus": null,
      "metadata": null,
      "status": "ready",
      "playbackId": "Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
      "maxResolutionTier": "1080p",
      "renditions": [
        { "name": "1080p", "width": 1920, "height": 1080, "bitrate": 3565000, "bytes": 55480000, "codecs": "avc1.640028,mp4a.40.2" },
        { "name": "720p", "width": 1280, "height": 720, "bitrate": 1161000, "bytes": 18070000, "codecs": "avc1.64001f,mp4a.40.2" },
        { "name": "360p", "width": 640, "height": 360, "bitrate": 261000, "bytes": 4060000, "codecs": "avc1.64001e,mp4a.40.2" }
      ],
      "storedBytes": 142300000,
      "errorReason": null,
      "deletedAt": null,
      "createdAt": "2025-06-15T10:30:00.000Z",
      "updatedAt": "2025-06-15T10:32:00.000Z",
      "takenDown": false,
      "hlsUrl": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/master.m3u8",
      "mp4Url": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/video.mp4",
      "posterUrl": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/poster.jpg",
      "outputs": { "hls": "ready", "mp4": "ready" },
      "shareUrl": "https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
      "embedUrl": "https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/embed"
    },
    {
      "id": "def456ghi789",
      "appId": "app_789",
      "externalUserId": "user_42",
      "name": "Untitled",
      "duration": null,
      "durationSeconds": null,
      "width": null,
      "height": null,
      "fps": null,
      "transcriptionStatus": null,
      "metadata": null,
      "status": "uploading",
      "playbackId": "Hn5tW2c8Jx4Pq7Ld9Vs1Ry3M",
      "maxResolutionTier": "1080p",
      "renditions": [],
      "storedBytes": null,
      "errorReason": null,
      "deletedAt": null,
      "createdAt": "2025-06-15T10:20:00.000Z",
      "updatedAt": "2025-06-15T10:20:00.000Z",
      "takenDown": false,
      "hlsUrl": null,
      "mp4Url": null,
      "posterUrl": null,
      "outputs": { "hls": "processing", "mp4": "processing" },
      "shareUrl": "https://cap.so/dev/Hn5tW2c8Jx4Pq7Ld9Vs1Ry3M",
      "embedUrl": "https://cap.so/dev/Hn5tW2c8Jx4Pq7Ld9Vs1Ry3M/embed"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "hasMore": false }
}

pagination.hasMore is true when more videos follow this page. Request the next page with offset raised by limit.

Get Video

Retrieve a single video by ID.

GET /api/developer/v1/videos/:id

Path parameters:

ParameterTypeDescription
idstringThe video ID

Query parameters:

ParameterTypeRequiredDescription
userIdstringNoReturn the video only when it was created with this userId. Any other video answers 404 with the code video_not_found, so your server can pass its signed-in user straight through
externalUserIdstringNoAnother name for userId

The match follows the same rules as List Videos: it is exact, and an empty value, a repeated parameter or any other query parameter returns 400.

Example request:

curl https://cap.so/api/developer/v1/videos/abc123def456 \
  -H "Authorization: Bearer csk_your_secret_key_here"

Example response:

{
  "data": {
    "id": "abc123def456",
    "appId": "app_789",
    "externalUserId": "user_42",
    "name": "Product Demo",
    "duration": 124.5,
    "durationSeconds": 124.5,
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "transcriptionStatus": null,
    "metadata": null,
    "status": "ready",
    "playbackId": "Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
    "maxResolutionTier": "1080p",
    "renditions": [
      { "name": "1080p", "width": 1920, "height": 1080, "bitrate": 3565000, "bytes": 55480000, "codecs": "avc1.640028,mp4a.40.2" },
      { "name": "720p", "width": 1280, "height": 720, "bitrate": 1161000, "bytes": 18070000, "codecs": "avc1.64001f,mp4a.40.2" },
      { "name": "360p", "width": 640, "height": 360, "bitrate": 261000, "bytes": 4060000, "codecs": "avc1.64001e,mp4a.40.2" }
    ],
    "storedBytes": 142300000,
    "errorReason": null,
    "deletedAt": null,
    "createdAt": "2025-06-15T10:30:00.000Z",
    "updatedAt": "2025-06-15T10:32:00.000Z",
    "takenDown": false,
    "hlsUrl": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/master.m3u8",
    "mp4Url": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/video.mp4",
    "posterUrl": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/poster.jpg",
    "outputs": { "hls": "ready", "mp4": "ready" },
    "shareUrl": "https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
    "embedUrl": "https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/embed",
    "captions": [{ "language": "en", "url": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/captions-en.vtt" }]
  }
}

Get Video Status

Check whether a video can be played yet.

GET /api/developer/v1/videos/:id/status

Path parameters:

ParameterTypeDescription
idstringThe video ID

Query parameters:

ParameterTypeRequiredDescription
userIdstringNoReturn the status only when the video was created with this userId. Any other video answers 404 with the code video_not_found
externalUserIdstringNoAnother name for userId

The match follows the same rules as List Videos: it is exact, and an empty value, a repeated parameter or any other query parameter returns 400.

Example request:

curl https://cap.so/api/developer/v1/videos/abc123def456/status \
  -H "Authorization: Bearer csk_your_secret_key_here"

Example response:

{
  "data": {
    "id": "abc123def456",
    "externalUserId": "user_42",
    "duration": 124.5,
    "durationSeconds": 124.5,
    "width": 1920,
    "height": 1080,
    "transcriptionStatus": null,
    "ready": true,
    "status": "ready",
    "errorReason": null,
    "playbackId": "Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G",
    "renditions": [
      { "name": "1080p", "width": 1920, "height": 1080, "bitrate": 3565000, "bytes": 55480000, "codecs": "avc1.640028,mp4a.40.2" },
      { "name": "720p", "width": 1280, "height": 720, "bitrate": 1161000, "bytes": 18070000, "codecs": "avc1.64001f,mp4a.40.2" },
      { "name": "360p", "width": 640, "height": 360, "bitrate": 261000, "bytes": 4060000, "codecs": "avc1.64001e,mp4a.40.2" }
    ],
    "takenDown": false,
    "hlsUrl": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/master.m3u8",
    "mp4Url": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/video.mp4",
    "posterUrl": "https://cap.so/api/developer/playback/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/poster.jpg",
    "outputs": { "hls": "ready", "mp4": "ready" }
  }
}

The status field moves from uploading to processing when the upload completes, then to ready or errored. ready is true when status is ready. When status is errored, errorReason says why.

A failed video is not billed. It stays in the list with its errorReason, and its uploaded file is removed 24 hours after processing started, after which storedBytes is 0. It cannot be processed again, so create a new video and upload the file to that one.

Poll this endpoint every 3 seconds after completing an upload, and stop when status is ready or errored. Each call counts toward the key's 300 requests per minute.

A video is ready as soon as its first output can be played, so playback can start while the rest is still encoding. The playback URLs are null until then. hlsUrl is an adaptive HLS master playlist, mp4Url is a progressive MP4 and posterUrl is a poster image. They need no API key and can be loaded from any origin. Play a Video shows how to use them, and Delete Video says when they stop working.

On a ready video, one of hlsUrl and mp4Url can still be null while that output finishes encoding. It is filled in later without the video leaving ready, and renditions is filled in together with hlsUrl. Play whichever URL is present. A player that wants HLS should keep polling after ready until hlsUrl is set, and can play mp4Url in the meantime. A webhook's video.ready is sent once every playback URL is ready instead.

outputs says whether a null URL is still coming. Each of outputs.hls and outputs.mp4 is ready when its URL is set, processing while it is being encoded or will be retried, and failed when it will not be produced. A video can be ready with one output failed, so stop waiting for that URL and play the other. none only appears on videos uploaded before encoding existed. While takenDown is true the playback URLs are null whatever outputs says, and outputs keeps describing what was encoded.

externalUserId is the userId the video was created with, so one call can confirm the owner and read the status.

takenDown is true when Cap has taken the video down after a report. Its playback URLs are then null, its playback files answer 410 Gone to every new request, and its page and embed show only "This video is not available." A player that already loaded the video holds signed media links that keep working until they expire, at most 18 hours later. status does not change, and the video is stored and billed as before. Email hello@cap.so about a takedown.

transcriptionStatus is null. Uploaded videos are not transcribed automatically. To get text, send the file to Transcripts.

Delete Video

Delete a video. It is excluded from every query straight away, and its playback URLs stop answering new viewers within about a minute. Its files (the upload and every encoded output) are removed within about five minutes, and links that were already handed out stop working within about ten minutes of the delete. That includes signed media URLs, however long they still have before they expire. If the video was still being encoded when it was deleted, anything the encoder writes afterwards is removed within four hours. A video deleted while it is being processed is charged its first month too, as Billing explains.

Deleting a video this app already deleted returns success again, so the call is safe to repeat. An ID that never belonged to this app returns 404.

DELETE /api/developer/v1/videos/:id

Path parameters:

ParameterTypeDescription
idstringThe video ID

Query parameters:

ParameterTypeRequiredDescription
userIdstringNoDelete the video only when it was created with this userId. Any other video answers 404 with the code video_not_found and is left alone
externalUserIdstringNoAnother name for userId

The match follows the same rules as List Videos: it is exact, and an empty value, a repeated parameter or any other query parameter returns 400.

Example request:

curl -X DELETE https://cap.so/api/developer/v1/videos/abc123def456 \
  -H "Authorization: Bearer csk_your_secret_key_here"

Example response:

{
  "success": true
}

Transcripts

Send an audio or video file and get text back. Transcription costs $0.10 per audio hour, billed by the second from the app's credit balance.

A transcript moves through these statuses: uploading (waiting for its file), queued, processing, then complete or error. Poll Get Transcript every 5 seconds until the status is complete or error. Each key allows 300 requests per minute.

To wait on several transcripts, poll them as a batch with one List Transcripts call per status instead of one Get Transcript each: GET /api/developer/v1/transcripts?status=queued&limit=100, then status=processing. Ask for queued first: a transcript only moves from queued to processing to a final status, so one missing from both lists has finished. Read it with Get Transcript for its text, and keep it in the batch if the status it returns is not yet complete or error. An app has at most 20 transcripts in flight, and getting each of 20 every 5 seconds takes 240 requests a minute, most of a key's limit, while the two list calls take 24.

An app can have 20 transcripts queued or processing at once. Starting another answers 429 with the code too_many_transcripts and a Retry-After header of 15 seconds. Wait for one to finish, then send the request again. Transcripts in uploading do not count until they are started.

A transcript request can be refused. The response carries a code and a message, and these are all the codes the transcript routes return besides the ones every route shares (see Error Handling):

StatusCodeMeaning
400invalid_urlThe URL is missing, longer than 2,048 characters, not http or https, on a port other than the default, or carries a username or password
400url_not_publicThe URL points to a private or local address
400invalid_video_idvideoId is empty or longer than 64 characters
400invalid_nameThe name is longer than 255 characters
400invalid_languageThe language is not auto or one of the supported codes. The hint lists them
400invalid_user_idThe user ID is longer than 255 characters
400invalid_metadataThe metadata is not a JSON object under 8 KB
400invalid_content_lengthcontentLength is not a whole number of bytes from 1 to 2 GB
400invalid_file_nameThe file name is longer than 255 characters
400file_too_largeThe uploaded file is larger than 2 GB
400invalid_idempotency_keyThe Idempotency-Key is not 8 to 128 characters of letters, digits, dot, dash and underscore
400invalid_statusThe status filter is not one of the transcript statuses
400invalid_includeinclude has a value other than words or segments. The message names it
402out_of_creditThe app is in grace or paused because a storage or delivery charge could not be paid. The message says how much to add
402insufficient_creditsThe available balance is under $0.01. The message says how much to add
403infra_not_availableCap Infra is not enabled for this account
404transcript_not_foundNo transcript with this ID belongs to the app
404video_not_foundNo video with this ID belongs to the app, or it was deleted
409video_not_readyThe video is not ready yet, or it failed to process and has no file to transcribe. The message says which
409idempotency_conflictThe Idempotency-Key was already used with a different request, or for a transcript that was deleted. The message names the field that differs
409upload_not_foundThe file has not been uploaded yet. If the upload URL expired, repeat the create request with the same Idempotency-Key to get a new one
429too_many_transcriptsThe app already has 20 transcripts queued or processing. Wait for one to finish, then send the request again
503speech_unavailableTranscription is temporarily unavailable. Retry later

Transcribe a URL

POST /api/developer/v1/transcripts
FieldTypeRequiredDescription
urlstringOne of url or videoIdPublic http or https URL of an audio or video file
videoIdstringOne of url or videoIdID of a ready video of this app. See Transcribe a video you already uploaded
namestringNoDisplay name (defaults to the file name, or to the video's name)
languagestringNoThe language of the audio if you know it, or auto (default). See Languages
userIdstringNoYour own user identifier, used to filter lists. With videoId, leave it out to use the video's userId
metadataobjectNoYour own JSON object, under 8KB

Send exactly one of url or videoId. Both, or neither, returns 400 with the code invalid_request. Any other field returns 400 with the code invalid_request and names the field. Field names are case-sensitive.

The URL must use the default port, must not contain credentials and must resolve to a public address. Redirects are followed up to five times and each hop is checked the same way. Files can be up to 2 GB, or 400 MB when the server does not send a Content-Length. Audio can be up to 4 hours long.

The file must finish downloading within 15 minutes, however slowly the server sends it. A download that takes longer ends the transcript with source_unreachable and a message that says it timed out.

The query string and fragment of the URL are used to fetch the file and are never returned. source.url is the URL without them, so a signature on a private link does not come back in any response.

curl -X POST https://cap.so/api/developer/v1/transcripts \
  -H "Authorization: Bearer csk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: standup-2026-11-11" \
  -d '{"url": "https://example.com/standup.mp3"}'
{
  "data": {
    "id": "8kq2m4x7n1p3v5w",
    "status": "queued",
    "name": "standup",
    "source": { "type": "url", "url": "https://example.com/standup.mp3" },
    "videoId": null,
    "durationSeconds": null,
    "language": null,
    "wordCount": null,
    "costMicroCredits": 0,
    "costDollars": 0,
    "error": null,
    "userId": null,
    "metadata": null,
    "createdAt": "2026-11-11T10:30:00.000Z",
    "updatedAt": "2026-11-11T10:30:00.000Z",
    "completedAt": null
  }
}

Send an Idempotency-Key header so a retried request returns the same transcript instead of creating and billing a second one. The key is 8 to 128 characters from letters, digits, dot, dash and underscore. Any other character, such as a colon, slash or space, is refused with 400 invalid_idempotency_key.

A repeat must send the same body. The same key with a different url, videoId, contentLength, name, language, userId or metadata is refused with 409 idempotency_conflict, and the message names the field that differs. A repeat with videoId may leave out userId when the first request left it out or sent the video's own userId.

Languages

Leave language out, or send auto, and Cap detects the language and reports it as language on the transcript.

Send a code only when you know the language of the audio. Cap then skips detection, uses its model for that language and reports that code as language. It does not translate, and it does not check the code against the audio: audio in another language is still transcribed as spoken and labelled with the code you sent.

Supported codes: en English, es Spanish, fr French, de German, pt Portuguese, it Italian, nl Dutch, pl Polish, ro Romanian, sk Slovak, ru Russian, tr Turkish, ja Japanese, ko Korean, zh Chinese (Simplified), ar Arabic, hi Hindi, bn Bengali, ta Tamil, te Telugu, mr Marathi, gu Gujarati, ur Urdu, fa Persian, he Hebrew. Any other value is refused with 400 invalid_language.

Transcribe a video you already uploaded

A video is not transcribed when it is uploaded, and it does not have to be uploaded again to get text. Once its status is ready, send its ID as videoId instead of a url:

curl -X POST https://cap.so/api/developer/v1/transcripts \
  -H "Authorization: Bearer csk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transcript-abc123def456" \
  -d '{"videoId": "abc123def456", "userId": "user_42"}'
{
  "data": {
    "id": "8kq2m4x7n1p3v5w",
    "status": "queued",
    "name": "Product walkthrough",
    "source": { "type": "video", "url": null },
    "videoId": "abc123def456",
    "durationSeconds": null,
    "language": null,
    "wordCount": null,
    "costMicroCredits": 0,
    "costDollars": 0,
    "error": null,
    "userId": "user_42",
    "metadata": null,
    "createdAt": "2026-11-11T10:30:00.000Z",
    "updatedAt": "2026-11-11T10:30:00.000Z",
    "completedAt": null
  }
}
  • The video must belong to the app that owns the key, not be deleted and be ready. An unknown or deleted video returns 404 video_not_found. A video that is still uploading or processing returns 409 video_not_ready: wait for ready and send the request again. A video that failed to process has no file to transcribe and returns the same code.
  • Cap reads the video's stored MP4 directly. Nothing is downloaded, so the 2 GB limit and the 15 minute download limit for URL transcripts do not apply. Audio can still be up to 4 hours long.
  • It costs the transcript price only, $0.10 per audio hour. Reading the stored video is not charged, and the video's storage charge does not change.
  • name, language, userId, metadata and the Idempotency-Key header work as they do for a URL. The name defaults to the video's name.
  • The transcript carries the video's ID as videoId, and source.type is video. videoId is null on every other transcript.
  • When a transcript of a video completes with speech, Cap writes a WebVTT captions file for the video in that language, from the newest completed transcript of the video in that language.
  • The hosted player and the embed then show a captions button, and the c key turns captions on and off. Add captions=1 to embedUrl to start with them on. See Embed Parameters.
  • The transcript is its own object. The video's transcriptionStatus does not change, and deleting the video leaves the transcript and its text. A transcript whose video is deleted before it runs ends with source_missing and is not charged.
  • Sending the video's mp4Url as url still works as a URL transcript. It is not linked to the video: its videoId is null.

Transcribe a file

Uploading takes three calls: create the transcript, PUT the file, then start it.

POST /api/developer/v1/transcripts/uploads
FieldTypeRequiredDescription
contentLengthintegerYesExact file size in bytes, up to 2 GB
fileNamestringNoOriginal file name
name, language, userId, metadataNoSame as above

Any other field returns 400 with the code invalid_request and names the field.

The response is the transcript in the uploading status plus an upload object with a signed URL that is valid for one hour. Audio can be up to 4 hours long.

FILE=standup.m4a
SIZE=$(wc -c < "$FILE" | tr -d ' ')
 
CREATED=$(curl -s -X POST https://cap.so/api/developer/v1/transcripts/uploads \
  -H "Authorization: Bearer csk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d "{\"fileName\": \"$FILE\", \"contentLength\": $SIZE}")
 
ID=$(echo "$CREATED" | jq -r .data.id)
 
curl -X PUT -T "$FILE" "$(echo "$CREATED" | jq -r .data.upload.url)"
 
curl -X POST "https://cap.so/api/developer/v1/transcripts/$ID/start" \
  -H "Authorization: Bearer csk_your_secret_key_here"

A single signed PUT is used instead of a multipart upload because it is one request any HTTP client can make. The upload must be exactly contentLength bytes. A PUT whose length differs is refused by storage with 403 SignatureDoesNotMatch, because the length is part of the signed URL. Starting a transcript twice is safe: the second call returns the transcript unchanged.

The upload URL is valid for one hour. While the status is uploading, Get Transcript returns upload.expiresAt, the time the latest URL stops working. To get a new URL, repeat the create request with the same Idempotency-Key and the same body. A transcript created without a key cannot get a new URL, so create another.

Get Transcript

GET /api/developer/v1/transcripts/:id

Returns the transcript. Once the status is complete the response includes text, durationSeconds, language, wordCount and the cost. Add ?include=words or ?include=segments (or both, comma-separated) for timings in seconds. Any other include value is refused with 400 invalid_include.

{
  "data": {
    "id": "8kq2m4x7n1p3v5w",
    "status": "complete",
    "name": "standup",
    "source": { "type": "upload", "url": null },
    "videoId": null,
    "durationSeconds": 754.2,
    "language": "en",
    "wordCount": 1893,
    "text": "Morning everyone. Quick update from my side...",
    "costMicroCredits": 2094,
    "costDollars": 0.02094,
    "error": null,
    "userId": null,
    "metadata": null,
    "createdAt": "2026-11-11T10:30:00.000Z",
    "updatedAt": "2026-11-11T10:30:21.000Z",
    "completedAt": "2026-11-11T10:30:21.000Z"
  }
}

With ?include=words,segments a complete transcript also carries:

{
  "data": {
    "id": "8kq2m4x7n1p3v5w",
    "status": "complete",
    "text": "Morning everyone. Quick update from my side.",
    "words": [
      { "text": "Morning", "start": 0.48, "end": 0.88 },
      { "text": "everyone.", "start": 0.88, "end": 1.44 },
      { "text": "Quick", "start": 1.84, "end": 2.16 },
      { "text": "update", "start": 2.16, "end": 2.56 },
      { "text": "from", "start": 2.56, "end": 2.72 },
      { "text": "my", "start": 2.72, "end": 2.88 },
      { "text": "side.", "start": 2.88, "end": 3.36 }
    ],
    "segments": [
      { "text": "Morning everyone.", "start": 0.48, "end": 1.44 },
      { "text": "Quick update from my side.", "start": 1.84, "end": 3.36 }
    ]
  }
}

start and end are seconds from the start of the audio. A word's start is usually within 0.1 seconds of where it is spoken. Its end can run up to 0.4 seconds late and is often the start of the next word, so the timings suit captions and seeking rather than tight cuts at word ends. Timings do not drift on long files.

Audio with no speech is not a failure. The transcript completes with text set to "" and wordCount set to 0, and it is billed for its length like any other transcript. A complete transcript with a wordCount of 0 is how you tell that no speech was found.

A failed transcript has the status error and an error object with one of these codes. A failed transcript is never charged:

CodeMeaning
insufficient_creditsThe available balance could not cover the hold for the transcript, or the transcript itself. The message says how much was needed
source_unreachableThe URL could not be downloaded: it answered with an error, redirected too many times, ended early, or did not finish within 15 minutes. The message says which
source_blockedThe URL, or a redirect from it, did not point to a public address
source_too_largeThe file is larger than 2 GB
source_missingThe uploaded file was not found
no_audio_trackThe file has no audio
unsupported_formatThe file is not a self-contained audio or video file. Playlists and manifests are not accepted. When a URL returns a web page, the message says so
no_speechNo longer returned. Audio with no speech now completes with empty text. Transcripts that failed this way before the change keep the code
duration_too_longThe audio is longer than 4 hours
upload_expiredThe file was not uploaded within 24 hours
timed_outThe transcript did not finish in time
transcription_failedAnything else

List Transcripts

GET /api/developer/v1/transcripts
ParameterTypeRequiredDescription
userIdstringNoOnly return transcripts created with exactly this userId
statusstringNoFilter by status
limitintegerNoNumber of results (default 50, max 100)
offsetintegerNoNumber of results to skip (default 0)

Returns { "data": [...], "pagination": { "limit", "offset", "hasMore" } }, newest first. List items do not include text.

The userId filter matches the exact value: alice, Alice and àlice are three different users. Spaces around the value are ignored, as they are when a transcript is created. A userId that is present but empty returns 400 with the code invalid_user_id and never the whole list, so a missing session value cannot show one user everyone's transcripts.

Delete Transcript

DELETE /api/developer/v1/transcripts/:id

Deletes the transcript, its text and its stored files. A transcript deleted before its audio is sent to speech recognition is not charged. One deleted after that is still charged for the length of its audio when it finishes, because the audio was already transcribed. It stays deleted: it is not listed and its text is not kept.

Deleting a transcript this app already deleted returns success again, so the call is safe to repeat. An ID that never belonged to this app returns 404.

Transcript billing

  • The price is $0.10 per audio hour, which is 10,000 micro-credits. Cap measures the audio itself, rounds its length to the nearest whole second with a minimum of one, and charges those seconds at the hourly rate, rounded down to a whole micro-credit and never less than one. The example above is 754.2 seconds, billed as 754 seconds: 754 × 10,000 ÷ 3,600 is 2,094.4, so it costs 2,094 micro-credits. A length sent by the client is never used.
  • Creating or starting a transcript needs an app in good standing and an available balance of at least 1,000 micro-credits ($0.01). Otherwise the API answers 402, with code set to out_of_credit when the app is in grace or paused and insufficient_credits when the balance is under the minimum. The message says how much to add.
  • Credits are taken once, when the transcript completes. A transcript that is retried internally is never charged twice.
  • Audio with no speech is billed for its length and returns an empty transcript, because the audio was extracted and run through speech recognition.
  • Never charged: a transcript that ends in error for any reason (a file that is not audio or video, a file with no audio track, a source that cannot be fetched or is too large, audio over 4 hours, not enough credit, a timeout, or a failure on our side), and a transcript deleted before its audio is sent to speech recognition.
  • A transcript deleted while its audio is being transcribed is charged for the length of its audio, like one that completes. The credit held for it stays held until then.
  • Starting holds up to the cost of four hours ($0.40) until the audio is measured, then the hold drops to the real cost. The hold is placed before the file is downloaded or processed and nothing is charged for it. It is sized from the file: a file under 180 KB holds $0.01, a file of 7.2 MB or more holds the full $0.40, and a URL that does not report its size holds $0.40. A stored video is held for its known length instead, so a 10 minute video holds under $0.02. The available balance is your balance minus those holds.
  • If the available balance cannot cover the hold, the transcript ends with insufficient_credits before the file is downloaded or processed, and the error message says how much was needed. When other running transcripts hold the credit, it waits for them for up to 15 minutes first, so a batch started together runs through as holds are released.
  • Credit held for a running transcript is left alone by the daily storage charge and is not counted when uploads are admitted. If the balance still cannot pay for a transcript in full when it finishes, the transcript ends with insufficient_credits, its text is discarded and nothing is charged. Top up and submit it again.
  • Cap deletes the source file once the transcript finishes. A stored video's own file is never touched. The text and timings are kept until you delete the transcript.

Get Usage

Retrieve your app's credit balance, video totals, standing, what it needs to take an upload, what storage costs per day and the rates those costs are worked out from.

GET /api/developer/v1/usage

Example request:

curl https://cap.so/api/developer/v1/usage \
  -H "Authorization: Bearer csk_your_secret_key_here"

Example response:

{
  "data": {
    "appId": "app_789",
    "balanceMicroCredits": 500000,
    "balanceDollars": "5.00",
    "availableMicroCredits": 460000,
    "heldMicroCredits": 40000,
    "speech": {
      "periodStart": "2026-11-01T00:00:00.000Z",
      "seconds": 5412.6,
      "microCredits": 15030,
      "transcripts": 9
    },
    "delivery": {
      "minutes": 1248.5,
      "minutesByTier": { "360p": 12.5, "720p": 336, "1080p": 900, "1440p": 0, "2160p": 0 },
      "finalThrough": "2026-11-18"
    },
    "totalVideos": 23,
    "uploadingVideos": 1,
    "totalDurationMinutes": 87.5,
    "standing": { "state": "active", "pausesAt": null },
    "upload": {
      "allowed": true,
      "reason": null,
      "requiredMicroCredits": 1190,
      "shortfallMicroCredits": 0,
      "message": null
    },
    "storage": {
      "minutesByTier": { "1080p": 87.5, "1440p": 0, "2160p": 0 },
      "dailyChargeMinutesByTier": { "1080p": 60, "1440p": 0, "2160p": 0 },
      "dailyMicroCredits": 170,
      "monthlyMicroCredits": 5100,
      "storedMonthlyMicroCredits": 7438
    },
    "rates": {
      "microCreditsPerDollar": 100000,
      "storageDollarsPer1000MinutesPerMonth": { "1080p": 0.85, "1440p": 1.45, "2160p": 2.8 },
      "deliveryDollarsPer1000Minutes": 0.95,
      "speechDollarsPerHour": 0.1,
      "uploadAdmissionDays": 7
    }
  }
}

Credits are tracked in micro-credits (1 dollar = 100,000 micro-credits). balanceDollars is the same balance in dollars, exact and never rounded up: two decimals when it is a whole number of cents and five otherwise, so 2,999,901 micro-credits is "29.99901". Billing explains every charge.

appId is the app the secret key belongs to. Credit is added on that app's Billing page, https://cap.so/dashboard/infra/{appId}/billing.

Speech. speech is what speech to text has cost in the current calendar month, counted in UTC from periodStart: the measured audio seconds of completed transcripts, the micro-credits charged for them and how many there were. Each transcript is charged on its length rounded to a whole second and then down to a whole micro-credit, so seconds times the rate can differ slightly from microCredits: for the exact charge use microCredits, or each transcript's costMicroCredits. Deleted transcripts stay counted, so the figure reconciles with the balance. heldMicroCredits is credit held by transcripts that are running now, and availableMicroCredits is the balance minus those holds, which is what a new transcript or upload is checked against.

Delivery. delivery is the minutes of video delivered to your viewers in the same calendar month as speech, in total and for each rendition tier, and it is null until delivery has been measured for the app. Delivered minutes are the media seconds in the video bytes we actually send, counting part of a segment in proportion; transfers the viewer abandons part-way aren't counted. For HLS it counts the exact seconds of the segments served, from each segment's EXTINF duration and EXT-X-BYTERANGE range. For MP4 downloads it counts the bytes served divided by the file's average bytes per second. Playlists, posters, HEAD requests, responses other than 200 or 206 and empty responses are never counted. A day's figures become final once all of its delivery logs are in, normally in the first update after 02:00 UTC two days later, and finalThrough is the latest final day in the period, so today and yesterday may still change.

Totals. totalVideos counts videos that are stored and ready to play, and totalDurationMinutes is their combined length, equal to the sum of storage.minutesByTier. uploadingVideos counts videos that were created and have not completed an upload. A video that is still encoding, or that failed or was refused, is in neither count. List Videos returns it with its status.

Rates. rates holds the prices and rules the other fields are built from, so a client does not need to hard-code them: dollars to store 1,000 minutes for a 30 day month in each tier, dollars for each 1,000 delivered minutes, dollars to transcribe one hour of audio, and the number of days of storage the balance must cover before an upload is accepted.

What is billed. Uploading and encoding are free. From November 13, 2026, each video is charged its first month of storage when it first becomes ready, by its length and resolution tier, and is charged once a day after that month, with a month counted as 30 days. Videos that were ready before November 13, 2026 keep the daily charge. Delivery is billed per delivered minute, one flat rate at every resolution priced in Billing, and charged once a day when the day's figures become final. Delivery above says how delivered minutes are measured. Billing has the daily arithmetic, worked examples, top-ups, codes, auto top-up and what happens when credit runs out.

TierPixels (width times height)Storage per 1,000 minutes per month
1080pup to 2,073,600$0.85
1440pup to 4,194,304$1.45
2160pabove 4,194,304$2.80

A video is billed at the lower of two tiers: the tier its source falls in by pixel count, and the maxResolutionTier it was created with. A 3840 by 2160 upload created with the default 1080p tier is encoded and billed at 1080p. storage.minutesByTier groups minutes the same way.

Storage. storage.minutesByTier is what is stored: the minutes of the videos counted in totalVideos, in each tier. storage.dailyChargeMinutesByTier is the part of it the daily charge covers, the videos past their first month, and dailyMicroCredits and monthlyMicroCredits are what those cost per day and per 30 day month. A video in its first month counts in minutesByTier and not in the daily figures, because its month was charged when it became ready. storedMonthlyMicroCredits is what a 30 day month costs for everything in minutesByTier, first months included: the monthly cost of what is stored now.

Uploading. upload.allowed is true when the app is in good standing and its balance pays for the first month of every video still encoding and covers 7 days of storage for the videos past their first month. upload.requiredMicroCredits is that amount and upload.shortfallMicroCredits is how much to add.

Standing. standing.state is one of:

StateMeaning
activeIn good standing.
graceA storage or delivery charge, for a day or for a video's first month, was more than the balance. The balance was taken to zero, uploads are blocked, and playback continues until pausesAt, 7 days after the app first fell short.
pausedPlayback is paused until credits are added. Videos stay stored.

Once the available balance covers the charge that fell short, one day of storage, a video's first month or one day of delivery, the app returns to active at once, whether credit was added or a transcript's hold was released. A later charge falling short starts a new grace period. What it could not pay is not charged afterwards.

List Transactions

Retrieve the app's ledger: every credit added and every charge taken, newest first.

GET /api/developer/v1/transactions
ParameterTypeRequiredDescription
limitintegerNoNumber of results (default 50, max 100)
offsetintegerNoNumber of results to skip (default 0)

Example request:

curl "https://cap.so/api/developer/v1/transactions?limit=2" \
  -H "Authorization: Bearer csk_your_secret_key_here"

Example response:

{
  "data": [
    {
      "id": "p4w8n2k6x1m9q3z",
      "type": "transcription",
      "description": "Transcription",
      "note": null,
      "amountMicroCredits": -2094,
      "amountDollars": "-0.02094",
      "balanceAfterMicroCredits": 497906,
      "balanceAfterDollars": "4.97906",
      "referenceType": "developer_transcript",
      "referenceId": "8kq2m4x7n1p3v5w",
      "createdAt": "2026-11-11T10:30:21.000Z"
    },
    {
      "id": "h7c3v9b5t2r8y4d",
      "type": "topup",
      "description": "Top-up",
      "note": null,
      "amountMicroCredits": 500000,
      "amountDollars": "5.00",
      "balanceAfterMicroCredits": 500000,
      "balanceAfterDollars": "5.00",
      "referenceType": "stripe_payment_intent",
      "referenceId": "pi_3Example",
      "createdAt": "2026-11-11T10:00:00.000Z"
    }
  ],
  "pagination": { "limit": 2, "offset": 0, "hasMore": false }
}

amountMicroCredits is positive for credit added, negative for a charge and 0 for a row that moved nothing, such as a declined auto top-up. balanceAfterMicroCredits is the balance once the row was applied, so each row's balance is the balance of the row before it plus its amount. The dollar fields are the same figures written exactly, never rounded.

id is the row's own ID. referenceType says what referenceId identifies:

typedescriptionreferenceTypereferenceId
topupTop-upstripe_payment_intentThe payment
topupCode redeemedstripe_checkout_sessionThe checkout a code covered in full
topupAuto top-upauto_top_upThe payment
topup_failedAuto top-up declinedauto_top_up_failedThe payment, or declined- and the UTC day when there was none
pro_creditCap Pro creditpro_monthly_creditThe month, as YYYY-MM
storage_dailyStoragestorage_dayThe UTC day, as YYYY-MM-DD
video_createStorage, first monthdeveloper_videoThe video ID
delivery_dailyDeliverydelivery_dayThe UTC day, as YYYY-MM-DD
transcriptionTranscriptiondeveloper_transcriptThe transcript ID
adjustmentAdjustmentmanualA note, when there is one
refundPayment reversedstripe_refundThe refund
adjustmentPayment disputedstripe_disputeThe dispute

A storage row is described as "Storage, part paid" or "Storage, unpaid" when the balance could not cover that day, and a first month row as "Storage, first month, part paid" or "Storage, first month, unpaid" when it could not cover that month. note holds a sentence of explanation for the rows that need one.

Rows written in the same second have the same createdAt. They are ordered so each balance follows from the row beneath it, within a page and across page edges, so walking the list with any limit returns the same order.

The console's Billing page shows the same rows and exports them all as CSV.

Webhooks

Have Cap call your server when a video is ready or has failed, instead of polling for it. Register an https URL for the app and Cap sends it a signed POST request for each event. The Webhooks guide covers the events, the request Cap sends, how to verify its signature, and retries.

RequestWhat it does
POST /api/developer/v1/webhooksCreate an endpoint. The response carries its signing secret, once
GET /api/developer/v1/webhooksList the app's endpoints with limit and offset
GET /api/developer/v1/webhooks/:idRead one endpoint and how Cap's last call to it went
PATCH /api/developer/v1/webhooks/:idChange url, events or enabled
DELETE /api/developer/v1/webhooks/:idDelete an endpoint
POST /api/developer/v1/webhooks/:id/rotate-secretReplace the signing secret. The new one is returned once
POST /api/developer/v1/webhooks/:id/testSend a test event and report what the endpoint answered

Example request:

curl -X POST https://cap.so/api/developer/v1/webhooks \
  -H "Authorization: Bearer csk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/cap", "events": ["video.ready", "video.errored"]}'

The events are video.ready and video.errored, and each carries the video as Get Video returns it. An app can have 5 endpoints.


SDK API Endpoints

The SDK API uploads a video's file from a browser or app. Every endpoint takes the upload token from Create Upload in the Authorization header. The token already names the video, so videoId in a request body is optional, and a videoId that is not the token's returns 403 with code video_mismatch.

StatuscodeMeaning
401invalid_upload_tokenThe token is missing, malformed or altered
401upload_token_expiredThe token is past expiresAt. Renew it from your server and continue the upload
403public_key_not_allowedA public key was sent. Public keys cannot create or upload videos
403origin_not_allowedThe token has a corsOrigin and the Origin header is different
403video_mismatchThe body names a video other than the token's
404video_not_foundThe token's video was deleted

Multipart Upload

After creating an upload, send its file in parts with the upload token:

  1. Initiate the upload to get an uploadId.
  2. Split the file into parts. Every part except the last must be at least 5 MB (5,242,880 bytes). Number the parts from 1 with no gaps. The whole file can be up to 36 GB, which is at most 6,867 parts.
  3. Get presigned URLs for the parts, up to 50 per request. PUT each part's bytes to its URL and keep the ETag response header.
  4. Complete the upload with the list of parts.

If the token expires before step 4, renew it and carry on from where the upload stopped.

Initiate Upload

POST /api/developer/sdk/v1/upload/multipart/initiate

Request body (JSON):

FieldTypeRequiredDescription
videoIdstringNoThe token's video ID
contentTypestringNoOne of video/mp4 (default), video/webm, video/quicktime, video/x-matroska or application/octet-stream. video/avi and video/x-msvideo are refused with 400 and the code unsupported_content_type, before anything is uploaded. Any other value is stored as video/mp4
contentLengthintegerNoSize of the whole file in bytes. A file over the token's maxBytes or over 36 GB is refused here with 400 and the code file_too_large, before anything is uploaded

Example request:

curl -X POST https://cap.so/api/developer/sdk/v1/upload/multipart/initiate \
  -H "Authorization: Bearer cut_your_upload_token_here" \
  -H "Content-Type: application/json" \
  -d '{"contentType": "video/mp4"}'

Example response:

{
  "uploadId": "multipart-upload-id"
}

A video keeps one open upload. Calling initiate again returns the same uploadId when the upload was opened in the last 6 hours, so the parts already sent are kept.

Get Presigned Part URL

Get presigned URLs to upload parts. One request signs up to 50 parts, so a large file needs a request per 50 parts and not one per part.

POST /api/developer/sdk/v1/upload/multipart/presign-part

Request body (JSON):

FieldTypeRequiredDescription
videoIdstringNoThe token's video ID
uploadIdstringYesThe upload ID from the initiate step
partNumbersinteger[]One of the two1 to 50 part numbers, each from 1 to 10,000
partNumberintegerOne of the twoA single part number, from 1 to 10,000

Send partNumbers or partNumber, not both.

Example request:

curl -X POST https://cap.so/api/developer/sdk/v1/upload/multipart/presign-part \
  -H "Authorization: Bearer cut_your_upload_token_here" \
  -H "Content-Type: application/json" \
  -d '{"uploadId": "multipart-upload-id", "partNumbers": [1, 2, 3]}'

Example response:

{
  "parts": [
    { "partNumber": 1, "presignedUrl": "https://..." },
    { "partNumber": 2, "presignedUrl": "https://..." },
    { "partNumber": 3, "presignedUrl": "https://..." }
  ]
}

A request with partNumber returns one URL as { "presignedUrl": "https://..." }. More than 50 part numbers, or an empty list, returns 400 with the code invalid_part_count. Signing does not contact storage, so an uploadId that is wrong or was aborted is not refused here: the PUT to its URL fails, and Complete Upload answers 404 with the code upload_not_found.

A token signs part numbers up to the last one its size limit allows: maxBytes divided by 5,242,880 and rounded up, or 6,867 for a token with no maxBytes. A higher part number returns 400 with the code part_number_too_large, and no part in that request is signed.

Each URL is valid for one hour, so sign parts shortly before you upload them and sign again for any part whose URL has expired. Upload a part by sending a PUT request to its URL with the bytes as the body and no extra headers:

curl -X PUT -T part-1.bin -D - "$PRESIGNED_URL"

Save the ETag header from the response for the completion step. Send it as it was returned. The quotes around it are optional.

Complete Upload

Finalize the upload after all parts have been uploaded.

POST /api/developer/sdk/v1/upload/multipart/complete

Request body (JSON):

FieldTypeRequiredDescription
videoIdstringNoThe token's video ID
uploadIdstringYesThe upload ID
partsarrayYesEvery uploaded part, at least one. A part left out of the list is left out of the video
parts[].partNumberintegerYesThe part number, from 1 to 10,000
parts[].etagstringYesThe ETag returned when the part was uploaded
parts[].sizenumberYesThe size of the part in bytes
durationInSecsnumberYesPositive video duration in seconds. It is replaced by the measured duration once processing has read the file
widthnumberNoVideo width in pixels
heightnumberNoVideo height in pixels
fpsnumberNoVideo frame rate

Example request:

curl -X POST https://cap.so/api/developer/sdk/v1/upload/multipart/complete \
  -H "Authorization: Bearer cut_your_upload_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "multipart-upload-id",
    "parts": [
      { "partNumber": 1, "etag": "\"9b2cf535f27731c974343645a3985328\"", "size": 5242880 },
      { "partNumber": 2, "etag": "\"3858f62230ac3c915f300c664312c63f\"", "size": 1048576 }
    ],
    "durationInSecs": 12.5
  }'

Example response:

{
  "success": true
}

Completing an upload charges nothing. The video's stored duration is the greater of the submitted duration and a minimum based on the part sizes reported by storage, bounded by what the uploaded bytes could hold and capped at four hours. Storage for the video is billed daily from then on, by its length and resolution tier.

A mistake in the request returns one of these:

StatuscodeMeaningWhat to do
400parts_requiredparts is empty.Send the partNumber and ETag of every part you uploaded.
400parts_mismatchA listed part is missing from storage, is listed twice or has a different ETag.Upload the missing part again, then send each part once with the ETag its PUT returned.
400part_too_smallA part other than the last is under 5 MB.Initiate again and upload the file in larger parts.
400file_too_largeThe parts add up to more than 36 GB, or more than the token's maxBytes. The upload was aborted and its parts were discarded.Export the video at a lower bitrate or split it, then initiate again on the same video and upload the smaller file.
404upload_not_foundNo open upload matches the uploadId. It was aborted or the ID is wrong.Initiate again and upload the parts again.

The balance must pay for the first month of storage of this video and of every other upload of the app still encoding, and cover 7 days of storage for the videos past their first month. If it does not, complete returns 402 with the same body as Create Upload, and the upload stays open so the same request succeeds after a top-up. The one exception is when several uploads finish at once and together exceed the balance: the 402 then carries "fileRemoved": true, the file that was just assembled has been removed, and it must be uploaded again once credit is added.

Each video accepts one completed upload, and its token is used up with it. Once the upload completes, initiate, presign-part and abort return 409 with the code upload_already_completed, and repeating complete returns { "success": true } without doing anything.

Complete can itself return 409 with a code:

codeMeaningWhat to do
completion_in_progressAnother request is completing this upload right now, for example your own earlier request whose response was lost.Wait for the seconds in the Retry-After header, then send the same complete request again, and repeat for as long as it answers this way. If the earlier request was cut off, that can last up to 15 minutes. Do not abort the upload or delete the video.
upload_removedThe upload sat unrecorded for more than a day and was removed.Create a new upload and send the file again.

Abort also returns 409 with completion_in_progress while a completion holds the video, without a Retry-After header. See Abort Upload for what to do. Every SDK API endpoint returns 404 with the code video_not_found once the video is deleted. To upload a new file, create a new upload.

Abort Upload

Cancel an in-progress multipart upload and discard its parts. Abort is safe to repeat: when no open upload matches the uploadId, for example because it was already aborted, it answers 200 with { "success": true } again.

If abort returns 409 with the code completion_in_progress, the upload is being completed and can no longer be aborted. Do not repeat the abort. From your server, wait until GET /api/developer/v1/videos/:id no longer shows the video as processing, then delete the video if you do not want it.

POST /api/developer/sdk/v1/upload/multipart/abort

Request body (JSON):

FieldTypeRequiredDescription
videoIdstringNoThe token's video ID
uploadIdstringYesThe upload ID to abort

Example response:

{
  "success": true
}

Play a Video

A ready video has three playback URLs, and a hosted player for when you do not want to build one.

FieldUse it forWhat it is
hlsUrlPlaybackAn adaptive HLS master playlist. The player picks a rendition for the viewer's connection and switches as it changes
mp4UrlThe fallback, and downloadsOne progressive MP4 file
posterUrlThe image shown before playback startsA JPEG frame from the video
shareUrl, embedUrlNo player to buildA hosted player page and an iframe embed. See Share and Embed

The playback URLs need no API key and answer any origin, so there is no CORS setup to do.

When a video has captions, hlsUrl lists them as WebVTT subtitle tracks, so hls.js, Safari and other HLS players can offer them with no extra setup.

FFmpeg 9.0.0 to 9.0.2 stop after the first segment of byte-range HLS. Use FFmpeg 8.x or a later 9.0 release, or the MP4 download.

Play with hls.js

Safari plays HLS by itself. Every other browser needs hls.js. This page plays the video everywhere, with the MP4 as the fallback:

<video id="player" controls playsinline poster="POSTER_URL"></video>
<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<script>
  const video = document.getElementById("player");
  const hlsUrl = "HLS_URL";
  const mp4Url = "MP4_URL";
  let hls = null;
 
  function fallBackToMp4() {
    const position = video.currentTime;
    const wasPlaying = !video.paused;
    if (hls) {
      hls.destroy();
      hls = null;
    }
    if (!mp4Url) return;
    video.src = mp4Url;
    video.currentTime = position;
    if (wasPlaying) video.play();
  }
 
  if (hlsUrl && window.Hls && Hls.isSupported()) {
    hls = new Hls({ capLevelToPlayerSize: true });
    hls.loadSource(hlsUrl);
    hls.attachMedia(video);
    hls.on(Hls.Events.ERROR, (event, data) => {
      if (data.fatal) fallBackToMp4();
    });
  } else if (hlsUrl && video.canPlayType("application/vnd.apple.mpegurl")) {
    video.src = hlsUrl;
    video.addEventListener("error", fallBackToMp4, { once: true });
  } else if (mp4Url) {
    video.src = mp4Url;
  }
</script>

Replace HLS_URL, MP4_URL and POSTER_URL with the video's hlsUrl, mp4Url and posterUrl. A ready video can still have hlsUrl or mp4Url set to null while that output finishes encoding. Pass null for that one and the page plays the other.

  • hls.js runs wherever the browser supports Media Source Extensions. A browser without them that plays HLS itself gets the playlist directly, and anything else gets the MP4.
  • Keep the checks in that order. canPlayType is not a test for Safari by itself, because Chrome answers it for HLS too.
  • If hls.js hits an error it cannot recover from, the page switches to the MP4 at the same position and keeps playing.
  • If the browser's own HLS player fails, the page loads the MP4 in its place. A viewer who had already pressed play may have to press it again.
  • capLevelToPlayerSize stops hls.js from loading a rendition larger than the player. Without it, a small player on a fast connection climbs to the largest rendition.
  • There is no start level to set. Players begin with the first rendition the master playlist lists, and Cap lists the largest one whose peak bitrate is at most 2.6 Mbps first, at 1080p or smaller. On most videos that is 720p.

Play in Safari

A page that only has to work in Safari needs no script:

<video src="HLS_URL" poster="POSTER_URL" controls playsinline></video>

If the video's hlsUrl is still null, use its mp4Url as the src.

Stable URLs, Redirects and Caching

  • hlsUrl, mp4Url and posterUrl are stable. Store them and reuse them for as long as the video exists.
  • mp4Url and posterUrl answer with a 302 redirect to a signed URL on the media host, v.cap.so. Browsers and video players follow it. Do not store the URL you were redirected to.
  • The playlists behind hlsUrl list signed media URLs on the same host. A signed URL works for at least 12 hours, and a file keeps the same signed URL for up to six hours, so a browser can reuse what it already downloaded when a viewer comes back. A player left paused for longer than 12 hours may have to load the playlist again before it can fetch more of the video.
  • Playback answers are cached for 60 seconds by browsers and shared caches, so a change such as a delete or a top-up can take up to a minute to show.

The page above recovers from expired media URLs by itself, by switching to the MP4. To stay on HLS, add this function to the same script. It loads the playlist again and returns to the same position:

function reloadPlaylist() {
  if (!hls) return;
  const position = video.currentTime;
  hls.once(Hls.Events.MANIFEST_PARSED, () => {
    video.currentTime = position;
  });
  hls.loadSource(hlsUrl);
}

Call it when a viewer comes back to a player that loaded its playlist more than 12 hours ago, then call video.play(). It does nothing once the page has switched to the MP4. In Safari, set video.src to the hlsUrl again and then set video.currentTime.

Shorter Playlists for Long Videos

A playlist lists one signed URL for every few seconds of video, so it grows with the video. For a 21 minute video the video and audio playlists are about 250 KB each, and a player loads both before it can start. On a slow connection that delays the first frame.

A player built on hls.js can ask for a shorter form by adding ?segments=short to hlsUrl:

hls.loadSource(`${hlsUrl}?segments=short`);
  • A playlist with more than 15 segments, about a minute of video, then signs only its first segment. It lists the rest by file name next to the playlist, and each of those answers with a 302 redirect to the signed URL, as mp4Url does. Shorter playlists are the same in both forms.
  • The master playlist passes the choice on to the playlists it lists, so the parameter on hlsUrl is all you add.
  • In our test with a 21 minute video the playlists loaded before playback went from about 500 KB to about 40 KB, and the first frame on a 400 kbps connection came about 8 seconds sooner. On a fast connection the first frame and seeking were unchanged.
  • Use it with hls.js. Leave it off for native HLS in Safari and for AVPlayer: those players ask for the redirect again on every segment, which made seeking slower in the same test.
  • Any other value of segments is ignored and you get the usual playlists.

Content Security Policy

A site with a Content Security Policy has to allow two hosts: https://cap.so, which serves the playback URLs, and https://v.cap.so, which serves the media they point to. For the hls.js page above:

connect-src https://cap.so https://v.cap.so;
media-src blob: https://cap.so https://v.cap.so;
img-src https://cap.so https://v.cap.so;
worker-src blob:;
DirectiveWhy
connect-srchls.js fetches the playlists from cap.so and the media from v.cap.so
media-srchls.js feeds the video element through a blob: URL. The two hosts cover the MP4 fallback and HLS in Safari
img-srcThe poster is loaded from cap.so and redirects to v.cap.so, so both are needed
worker-srchls.js does its work in a worker created from a blob: URL. Without this it still plays, on the main thread, and the browser logs a violation

The scripts need allowing too. Add the origin you load hls.js from to script-src. The page above also starts the player from an inline script, which a script-src without 'unsafe-inline' blocks, so the video never gets a source. Move that script into a file your policy allows, or give the tag a nonce or a hash that the policy lists.

A page that plays HLS in Safari without hls.js needs only media-src and img-src with the two hosts. To use embedUrl in an iframe, allow frame-src https://cap.so.

If you self-host Cap, use your own web origin and the host your playback URLs redirect to.

Bitrates

renditions[].bitrate is the average bitrate of a rendition. The BANDWIDTH in the master playlist is its peak, and players choose a rendition by the peak. The peak can be more than twice the average, most of all for screen recordings, so a viewer whose connection matches a rendition's bitrate can be given the one below it.

The MP4

mp4Url is a single file, at most the dimensions of the largest rendition. It is not part of the adaptive ladder, so every viewer gets the same file whatever their connection.

When the upload is already H.264 and fits the tier, Cap can keep its video as uploaded instead of encoding it again, and the MP4 then has the bitrate of the upload. On the 2160p tier that can be a source-quality 4K file, which is large. Use hlsUrl for playback on that tier, and keep mp4Url for downloads and as the last fallback.

When Playback Stops

  • The app is out of credit. When an app is paused, every playback URL answers 402 with a plain text reason: Playback is paused because the account that hosts this video is out of credit. Neither hls.js nor the MP4 can load, so the video element fires an error event. Listen for it to show your own message. Playback returns within a minute of credits being added. An app in grace still plays. See Get Usage for the standings.
  • The video was deleted. The playback URLs answer 404 with the plain text Not found. Delete Video gives the timings for new viewers and for links that were already handed out. A deleted video and an ID that never existed answer the same way.
  • An output is not encoded yet. A URL that is null in the API has nothing behind it yet and would answer 404. Wait for the field to be filled in.

Share and Embed

Every video has a hosted player, returned as shareUrl and embedUrl when you create an upload and when you get or list a video. Both are built from the video's playbackId, need no API key or sign-in, set no cookies and are kept out of search engines.

The player sets no cookies. Each time a page with the player loads, Cap records one anonymous view with the page's address, so plays can be counted.

  • shareUrl is a page with the player and the video's name. Send it to a viewer as a link. Pasted into a chat or a page builder, it previews as the video: the page carries og:video tags for the MP4 and an oEmbed link to https://cap.so/api/developer/oembed?url=SHARE_URL, which answers with the embed's iframe. A video in an app with Allowed Sites gets no iframe from it, since other sites could not show one.
  • embedUrl is the player alone, filling whatever frame you give it. Any site can load it in an iframe, unless you limit it to your own sites with Allowed Sites:
<iframe
  src="https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/embed"
  title="Product Demo"
  style="width: 100%; aspect-ratio: 16 / 9; border: 0"
  allow="autoplay"
  allowfullscreen
  loading="lazy"
></iframe>

allow="autoplay" lets a play command your page sends after a click start the video with sound. Firefox does not know that name and logs a harmless warning about it.

Set the iframe's aspect-ratio from the video's width and height. The links work as soon as the video is created: until it is ready the page says the video is processing and switches to the player by itself, and if processing failed it tells the viewer only that the video is not available. The reason is shown only to you, in errorReason and in the console. A deleted video returns 404, and a video in an app whose playback is paused says so.

Allowed Sites

Only these sites can embed your player. Add them under Allowed sites in the app's settings, or with cap developers domains add. With none added, any site can embed it.

  • Each entry is one site, such as https://myshop.com. A subdomain is a separate site, so add https://www.myshop.com on its own. Wildcards are not supported.
  • Only https sites are accepted, plus http://localhost for testing.
  • Once a site is added, embedUrl tells browsers that only the listed sites, and Cap's own pages, may show it in a frame. On any other site the browser refuses to show the frame, so the player never loads and sends no postMessage events, not even error.
  • A change to the list reaches every embed within a minute.
  • The list only controls embedding. shareUrl and the hlsUrl, mp4Url and posterUrl playback URLs stay open to everyone who has them.

Embed Parameters

Add these to embedUrl as query parameters, for example https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/embed?t=90&loop=1.

ParameterWhat it does
autoplay=1Starts playing when the player loads. A browser that refuses to autoplay with sound gets the video muted, and one that refuses autoplay altogether shows the paused player
muted=1Starts with the sound off. The viewer can turn it on
loop=1Starts again from the beginning when the video ends
t=90Starts at that time. Seconds work, with decimals such as t=12.5, and so do hours, minutes and seconds such as t=1m30s, t=90s or t=1h2m3s. A time past the end is ignored. shareUrl takes this parameter too
controls=0Hides the control bar. A play button stays on a paused video and the keyboard keeps working
captions=1Starts with captions on, for a video that has them. The viewer can turn them off

A value the player does not understand is ignored, and so is a parameter it does not know. To let an embed autoplay with sound where the browser permits it, add autoplay to the iframe's allow list.

Embed Options

These change how the embedded player looks and what it offers. They work only on embedUrl.

ParameterWhat it does
color=3b82f6Accent colour of the progress bar, the volume level and the ticks in the menus. Six or three hex digits, with or without # (write # as %23 in a URL)
radius=12Rounds the player's corners by that many pixels, from 0 to 24. A larger number is read as 24. The page around the player is see-through, so the corners show your page
quality=720Never plays a rendition taller than this, in Auto or from the menu. 720p works too. A video with nothing that small plays its smallest rendition
quality_menu=0Hides the quality menu. Auto keeps choosing the rendition
speed_menu=0Hides the playback speed menu
pip=0Hides the picture in picture button
fullscreen=0Hides the full screen button and turns off full screen from a double click or the f key
poster=0Shows no poster. The player stays black until it plays
keyboard=0Turns off the player's keyboard shortcuts, such as space, k, the arrows, m, f and c. Tab and Enter still reach every control

The player has no title of its own, so there is nothing to hide. The quality menu offers Auto and every rendition in every browser, including Safari on iPhone and iPad, where picking one keeps the time and whether the video was playing.

<iframe
  src="https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/embed?color=f97316&radius=12&quality=1080&speed_menu=0&pip=0"
  title="Product Demo"
  style="width: 100%; aspect-ratio: 16 / 9; border: 0; border-radius: 12px"
  allow="autoplay"
  allowfullscreen
  loading="lazy"
></iframe>

Player Events

The embedded player tells the page it sits on what happens, and takes commands from it, with postMessage. Every message is an object with type: "cap-player".

Events arrive as { type: "cap-player", event, currentTime, duration, paused, muted }, with times in seconds. duration is 0 until it is known. Events carry no links and nothing about the viewer, and are sent to any origin.

EventWhenExtra fields
readyThe player has loaded and takes commands
playPlayback starts or resumes
pausePlayback pauses
endedThe video reaches its end
timeupdateThe time moves while playing, at most about four times a second
qualitychangeThe rendition shown changes, or the viewer picks onequality such as "1080p", auto (true while Auto is on)
errorThe video stops being playable, the browser refused a play command, or the embed has nothing to playcode: "media" when playback fails, "play_refused", "unavailable" for a video that is not available, deleted or unknown, or "paused" while the app's playback is paused. With "unavailable" or "paused", no ready is sent and commands do nothing

Commands are sent to the iframe's contentWindow as { type: "cap-player", command }. The player takes them only from the page that embeds it, and ignores anything else.

CommandFieldsWhat it does
playPlays. Browsers refuse to start a video with sound before the viewer has interacted with the page, so start it muted or after a click
pausePauses
seektime, secondsMoves to that time. A time past the end moves to the end
muteTurns the sound off
unmuteTurns the sound on
setQualityquality"auto", or a rendition such as "720p", 720 or "4k". A rendition the video does not have is ignored
<iframe id="demo" src="https://cap.so/dev/Zk3vQ9s2Lm8Rt1Xy7Bc4Df6G/embed" title="Product Demo" style="width: 100%; aspect-ratio: 16 / 9; border: 0" allow="autoplay" allowfullscreen></iframe>
<script>
  const player = document.getElementById("demo");
  const send = (message) => player.contentWindow.postMessage({ type: "cap-player", ...message }, "https://cap.so");
  window.addEventListener("message", ({ source, data }) => {
    if (source !== player.contentWindow || data?.type !== "cap-player") return;
    if (data.event === "ready") send({ command: "seek", time: 30 });
    if (data.event === "ended") console.log("Reached the end");
  });
</script>

Check source against the iframe's contentWindow as above, so a message from another frame on your page is not taken for the player's.

What the Player Loads

Before the viewer presses play, the player loads the poster, the playlists and at most the first few seconds of video, so a page can hold several embeds without downloading them. It never holds back the load event of the page it sits on. loading="lazy" in the snippet goes further and leaves an embed below the fold unloaded until the viewer scrolls near it. An embed that is already in view loads at once.

Video Object Reference

The full video object returned by list and get endpoints:

FieldTypeDescription
idstringUnique video identifier
appIdstringThe developer app that owns this video
externalUserIdstring | nullYour external user identifier
namestringVideo display name
durationSecondsnumber | nullDuration in seconds (null until upload completes). Holds the submitted value at first and the measured value once processing has read the file. Null again for a failed video that processing had not measured yet, even if a length was reported when the upload completed. Transcripts use the same name
durationnumber | nullThe same value as durationSeconds, under its earlier name
widthnumber | nullMeasured source width in pixels (null until upload completes)
heightnumber | nullMeasured source height in pixels (null until upload completes)
fpsnumber | nullMeasured frames per second (null until upload completes)
transcriptionStatusstring | nullnull. Uploaded videos are not transcribed automatically
metadataobject | nullCustom metadata provided during creation
statusstringOne of: uploading, processing, ready, errored
errorReasonstring | nullWhy processing failed (null unless status is errored)
playbackIdstring | nullUnguessable ID the playback URLs are built from
maxResolutionTierstringHighest resolution the video is encoded at: 1080p, 1440p or 2160p
renditionsarrayEncoded HLS renditions, largest first, each with name, width, height, bitrate (average bits per second), bytes and codecs. Empty until hlsUrl is set
storedBytesnumber | nullBytes stored for the source and every encoded output. 0 once a failed video's files have been removed
hlsUrlstring | nullAdaptive HLS master playlist (null until it is encoded)
mp4Urlstring | nullProgressive MP4 (null until it is encoded)
posterUrlstring | nullPoster image (null until ready)
takenDownbooleantrue when Cap has taken the video down after a report. The playback URLs are then null, the playback files answer 410 Gone, and the page and embed show that the video is not available
outputsobjecthls and mp4, each processing, ready, failed or none, so you can tell an output that is still coming from one that will not come
shareUrlstring | nullHosted player page for the video (null only for a video with no playbackId)
embedUrlstring | nullThe same player with nothing around it, for an iframe (null only for a video with no playbackId)
captionsarrayCaption tracks from this video's complete transcripts, each with language and the url of its WebVTT file. The player and embed show the same tracks. Empty until a transcript created with this video's videoId completes with speech. A track is listed once its WebVTT file is written, usually a few seconds after the transcript completes, so its url answers as soon as it appears. Not in webhook payloads
importobjectOnly on a video made with Import from a URL, and only from Get Video and Get Video Status: sourceUrl, state (downloading, complete or failed) and errorCode. Not in List Videos or webhook payloads
deletedAtstring | nullDeletion timestamp (null for active videos)
createdAtstringCreation timestamp (ISO 8601)
updatedAtstringLast update timestamp (ISO 8601)

Best Practices

  • Use secret keys server-side only. The csk_ key should never appear in client-side code. Create each upload on your server and send only its cut_ upload token to the browser.
  • Poll video status after upload. After completing a multipart upload, poll GET /videos/:id/status every 3 seconds until status is ready or errored, then play hlsUrl when it is present and mp4Url otherwise. Keep polling until hlsUrl is set if the player should use HLS. See Play a Video.
  • Switch on code. Every error carries a stable code. The error text can change.
  • Watch the rate limit headers. A secret key allows 300 requests per minute and an upload token 1,200. Slow down as X-RateLimit-Remaining nears zero, and wait for Retry-After seconds after a 429.
  • Store your keys securely. Use environment variables or a secrets manager.
  • Check who is uploading before you create an upload. Your server decides who gets a token, so authenticate the user first and set userId to tie the video to them.
  • Scope every read to the signed-in user. Pass your session's user as userId when you list, get, check or delete a video on a user's behalf. Refuse the request on your side when there is no signed-in user, rather than sending an empty userId.
  • Monitor your credit balance. Use the usage endpoint to track the balance, standing and upload.allowed, and top up from your app's Billing page in Cap Infra. Auto top-up on that page adds credits from a saved card when the balance runs low.
  • Paginate large result sets. Use limit and offset to retrieve videos in batches. When the returned array length is less than limit, you have reached the end.
Can't find what you need?