API reference

Video

Video projects: proxies and mixdowns uploaded in parts, the poster frame, transcriptions into captions, and the app's limits and export presets.

Read the Guide

GET/v1/orgs/:orgId/video/files/:fileId/proxies

The project's finished proxies: each one's media item (mediaRef), name, type and size. Read a proxy through Office's GET …/office/files/:fileId/media/:mediaId.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

orgId
Organization id (org_…).
fileId
File id, as returned when the upload was created.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/video/files/{fileId}/proxies' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  proxies: {
    mediaId: string
    mediaRef: null | string
    name: string
    mime: string
    size: number
    createdAt: number
  }[]
}

POST/v1/orgs/:orgId/video/files/:fileId/proxies

Starts an upload into the project in parts: a proxy of a media item (mediaRef, MP4 or WebM, up to video.proxyMb) or, with purpose: "audio", the mixdown to transcribe. Answers mediaId, partSize, partCount and links for the first parts. Editors only.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

orgId
Organization id (org_…).
fileId
File id, as returned when the upload was created.

Request body

mediaRefstring
Up to 64 characters.
namestringrequired
1–255 characters.
sizeintegerrequired
≥ 1.
mimestringrequired
Up to 100 characters.
purpose"proxy" | "audio"

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/video/files/{fileId}/proxies' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "size": 1,
    "mime": "example"
  }'

Send it from this page with your session or a key.

Response 201

{
  mediaId: string
  uploadId: string
  partSize: number
  partCount: number
  urls: {
    [key: number]: string
  }
  expiresIn: number
}

POST/v1/orgs/:orgId/video/files/:fileId/proxies/:mediaId/parts

Links for more parts (parts, 1 to 100 part numbers).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

orgId
Organization id (org_…).
fileId
File id, as returned when the upload was created.
mediaId
A picture's or other media's id in a document, spreadsheet, presentation or video project (med_…): pictures, Video's proxies, its poster and transcription mixdowns.

Request body

partsinteger[]required
1–100 items. Each 1–10000.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/video/files/{fileId}/proxies/{mediaId}/parts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "parts": [
      1
    ]
  }'

Send it from this page with your session or a key.

Response 200

{
  urls: {
    [key: number]: string
  }
  expiresIn: number
}

POST/v1/orgs/:orgId/video/files/:fileId/proxies/:mediaId/complete

Finishes the upload once every part is in; it then counts against the space's storage.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

orgId
Organization id (org_…).
fileId
File id, as returned when the upload was created.
mediaId
A picture's or other media's id in a document, spreadsheet, presentation or video project (med_…): pictures, Video's proxies, its poster and transcription mixdowns.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/video/files/{fileId}/proxies/{mediaId}/complete' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  mediaId: string
  size: number
  mime: string
}

DELETE/v1/orgs/:orgId/video/files/:fileId/proxies/:mediaId

Deletes a proxy, a mixdown or an unfinished upload of one, giving its storage back (when its media item leaves the project, or to make it again). Editors only.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

orgId
Organization id (org_…).
fileId
File id, as returned when the upload was created.
mediaId
A picture's or other media's id in a document, spreadsheet, presentation or video project (med_…): pictures, Video's proxies, its poster and transcription mixdowns.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/video/files/{fileId}/proxies/{mediaId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  deleted: boolean
}

PUT/v1/orgs/:orgId/video/files/:fileId/poster

Saves the project's poster frame (the body: a WebP or JPEG of at most 1 MB). Drive's thumbnail of the project follows. Editors only.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

orgId
Organization id (org_…).
fileId
File id, as returned when the upload was created.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.
413Posters can be at most 1 MB.

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/video/files/{fileId}/poster' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  mediaId: string
  size: number
  mime: string
}

POST/v1/orgs/:orgId/video/files/:fileId/transcriptions

Captions from speech: the uploaded mixdown (audioMediaId, duration in flicks) or one media item (source: "media", mediaId) into a new caption track of sequenceId from from, in language (or auto), with up to speakers voices told apart. 202 with the job; the track arrives in the project when it's done. Counts against your daily transcription minutes.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

orgId
Organization id (org_…).
fileId
File id, as returned when the upload was created.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/video/files/{fileId}/transcriptions' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  transcription: {
    id: string
    fileId: string
    sequenceId: string
    status: "queued" | "done" | "failed" | "running"
    language: string
    detected?: string
    minutes: number
    trackId?: string
    cues?: number
    error?: string
    createdAt: number
  }
}

GET/v1/orgs/:orgId/video/files/:fileId/transcriptions/:transcriptionId

A transcription job: status (running, done, failed), the caption track it made (trackId) and its cue count, or why it failed.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

orgId
Organization id (org_…).
fileId
File id, as returned when the upload was created.
transcriptionId
A Video transcription job's id (vtr_…).

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/video/files/{fileId}/transcriptions/{transcriptionId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  transcription: {
    id: string
    fileId: string
    sequenceId: string
    status: "queued" | "done" | "failed" | "running"
    language: string
    detected?: string
    minutes: number
    trackId?: string
    cues?: number
    error?: string
    createdAt: number
  }
}

GET/v1/me/video/files/:fileId/proxies

The project's finished proxies: each one's media item (mediaRef), name, type and size. Read a proxy through Office's GET …/office/files/:fileId/media/:mediaId.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

fileId
File id, as returned when the upload was created.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl 'https://api.cactive.com.au/v1/me/video/files/{fileId}/proxies' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  proxies: {
    mediaId: string
    mediaRef: null | string
    name: string
    mime: string
    size: number
    createdAt: number
  }[]
}

POST/v1/me/video/files/:fileId/proxies

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

fileId
File id, as returned when the upload was created.

Request body

mediaRefstring
Up to 64 characters.
namestringrequired
1–255 characters.
sizeintegerrequired
≥ 1.
mimestringrequired
Up to 100 characters.
purpose"proxy" | "audio"

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X POST 'https://api.cactive.com.au/v1/me/video/files/{fileId}/proxies' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "size": 1,
    "mime": "example"
  }'

Send it from this page with your session or a key.

Response 201

{
  mediaId: string
  uploadId: string
  partSize: number
  partCount: number
  urls: {
    [key: number]: string
  }
  expiresIn: number
}

POST/v1/me/video/files/:fileId/proxies/:mediaId/parts

Links for more parts (parts, 1 to 100 part numbers).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

fileId
File id, as returned when the upload was created.
mediaId
A picture's or other media's id in a document, spreadsheet, presentation or video project (med_…): pictures, Video's proxies, its poster and transcription mixdowns.

Request body

partsinteger[]required
1–100 items. Each 1–10000.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X POST 'https://api.cactive.com.au/v1/me/video/files/{fileId}/proxies/{mediaId}/parts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "parts": [
      1
    ]
  }'

Send it from this page with your session or a key.

Response 200

{
  urls: {
    [key: number]: string
  }
  expiresIn: number
}

POST/v1/me/video/files/:fileId/proxies/:mediaId/complete

Finishes the upload once every part is in; it then counts against the space's storage.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

fileId
File id, as returned when the upload was created.
mediaId
A picture's or other media's id in a document, spreadsheet, presentation or video project (med_…): pictures, Video's proxies, its poster and transcription mixdowns.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X POST 'https://api.cactive.com.au/v1/me/video/files/{fileId}/proxies/{mediaId}/complete' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  mediaId: string
  size: number
  mime: string
}

DELETE/v1/me/video/files/:fileId/proxies/:mediaId

Deletes a proxy, a mixdown or an unfinished upload of one, giving its storage back (when its media item leaves the project, or to make it again). Editors only.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

fileId
File id, as returned when the upload was created.
mediaId
A picture's or other media's id in a document, spreadsheet, presentation or video project (med_…): pictures, Video's proxies, its poster and transcription mixdowns.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X DELETE 'https://api.cactive.com.au/v1/me/video/files/{fileId}/proxies/{mediaId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  deleted: boolean
}

PUT/v1/me/video/files/:fileId/poster

Saves the project's poster frame (the body: a WebP or JPEG of at most 1 MB). Drive's thumbnail of the project follows. Editors only.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

fileId
File id, as returned when the upload was created.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.
413Posters can be at most 1 MB.

curl -X PUT 'https://api.cactive.com.au/v1/me/video/files/{fileId}/poster' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  mediaId: string
  size: number
  mime: string
}

POST/v1/me/video/files/:fileId/transcriptions

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

fileId
File id, as returned when the upload was created.

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl -X POST 'https://api.cactive.com.au/v1/me/video/files/{fileId}/transcriptions' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  transcription: {
    id: string
    fileId: string
    sequenceId: string
    status: "queued" | "done" | "failed" | "running"
    language: string
    detected?: string
    minutes: number
    trackId?: string
    cues?: number
    error?: string
    createdAt: number
  }
}

GET/v1/me/video/files/:fileId/transcriptions/:transcriptionId

A transcription job: status (running, done, failed), the caption track it made (trackId) and its cue count, or why it failed.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: drive:read

Get an API key

Path parameters

fileId
File id, as returned when the upload was created.
transcriptionId
A Video transcription job's id (vtr_…).

Errors

403Personal files are only for the person, signed in.
403This key has no person behind it, so it can't open Drive files.
403The person who made this key isn't in the organization any more.

curl 'https://api.cactive.com.au/v1/me/video/files/{fileId}/transcriptions/{transcriptionId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  transcription: {
    id: string
    fileId: string
    sequenceId: string
    status: "queued" | "done" | "failed" | "running"
    language: string
    detected?: string
    minutes: number
    trackId?: string
    cues?: number
    error?: string
    createdAt: number
  }
}

GET/v1/video/config

Video's limits (limits, from Admin → Limits), the export presets (presets, with the platform's changes) and what Transcribe offers (transcribe: whether it's on, its languages and the minutes allowed). People only.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Errors

403Video's settings are for people signed in.

curl 'https://api.cactive.com.au/v1/video/config' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  limits: {
    "video.clipsPerProject": number
    "video.tracksPerSequence": number
    "video.mediaPerProject": number
    "video.mediaGb": number
    "video.proxyMb": number
    "video.maxExportSide": number
    "video.exportMinutes": number
    "video.cacheGb": number
    "video.historyStates": number
    "video.transcribeMinutesPerDay": number
    "video.transcribeMinutesPerJob": number
  }
  catalog: {
    id: "video.clipsPerProject" | "video.tracksPerSequence" | "video.mediaPerProject" | "video.mediaGb" | "video.proxyMb" | "video.maxExportSide" | "video.exportMinutes" | "video.cacheGb" | "video.historyStates" | "video.transcribeMinutesPerDay" | "video.transcribeMinutesPerJob"
    label: "History states" | "Clips per project" | "Tracks per sequence" | "Media items per project" | "Largest source file (GB)" | "Largest proxy (MB)" | "Largest export side (pixels)" | "Longest export (minutes)" | "Device cache, largest (GB)" | "Transcription per person per day (minutes)" | "Longest transcription (minutes)"
  }[]
  presets: {
    id: string
    label: string
    description?: string
    settings: {
      container: "mp4" | "webm"
      video: null | {
        codec: "av1" | "avc" | "hevc" | "vp9"
        width: number
        height: number
        frameRate: {
          num: number
          den: number
        }
        bitrate: number
        bitrateMode: "variable" | "constant"
        keyframeEvery: number
        profile?: string
        hardware: "no-preference" | "prefer-hardware" | "prefer-software"
      }
      audio: null | {
        codec: "aac" | "opus"
        sampleRate: 48000 | 44100
        channels: 2 | 1
        bitrate: number
      }
      timecodeOverlay?: boolean
      loudness?: null | {
        target: number
        truePeak: number
      }
    }
  }[]
  transcribe: {
    available: boolean
    languages: [{
      code: "en-AU"
      label: "English (Australia)"
    }, {
      code: "en-US"
      label: "English (US)"
    }, {
      code: "en-GB"
      label: "English (UK)"
    }, {
      code: "en-NZ"
      label: "English (New Zealand)"
    }, {
      code: "en-IN"
      label: "English (India)"
    }, {
      code: "en-IE"
      label: "English (Ireland)"
    }, {
      code: "en-ZA"
      label: "English (South Africa)"
    }, {
      code: "zh-CN"
      label: "Chinese (Simplified)"
    }, {
      code: "zh-TW"
      label: "Chinese (Traditional)"
    }, {
      code: "zh-HK"
      label: "Cantonese"
    }, {
      code: "es-ES"
      label: "Spanish (Spain)"
    }, {
      code: "es-US"
      label: "Spanish (US)"
    }, {
      code: "fr-FR"
      label: "French (France)"
    }, {
      code: "fr-CA"
      label: "French (Canada)"
    }, {
      code: "de-DE"
      label: "German"
    }, {
      code: "it-IT"
      label: "Italian"
    }, {
      code: "pt-BR"
      label: "Portuguese (Brazil)"
    }, {
      code: "pt-PT"
      label: "Portuguese (Portugal)"
    }, {
      code: "ja-JP"
      label: "Japanese"
    }, {
      code: "ko-KR"
      label: "Korean"
    }, {
      code: "hi-IN"
      label: "Hindi"
    }, {
      code: "ar-SA"
      label: "Arabic"
    }, {
      code: "ru-RU"
      label: "Russian"
    }, {
      code: "nl-NL"
      label: "Dutch"
    }, {
      code: "sv-SE"
      label: "Swedish"
    }, {
      code: "da-DK"
      label: "Danish"
    }, {
      code: "no-NO"
      label: "Norwegian"
    }, {
      code: "fi-FI"
      label: "Finnish"
    }, {
      code: "pl-PL"
      label: "Polish"
    }, {
      code: "tr-TR"
      label: "Turkish"
    }, {
      code: "el-GR"
      label: "Greek"
    }, {
      code: "he-IL"
      label: "Hebrew"
    }, {
      code: "id-ID"
      label: "Indonesian"
    }, {
      code: "ms-MY"
      label: "Malay"
    }, {
      code: "th-TH"
      label: "Thai"
    }, {
      code: "vi-VN"
      label: "Vietnamese"
    }, {
      code: "tl-PH"
      label: "Filipino"
    }, {
      code: "uk-UA"
      label: "Ukrainian"
    }]
    minutesPerDay: number
    minutesPerJob: number
  }
}