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.

See Video. A video project is an office file (application/vnd.si.video), so it's created, opened, co-edited, versioned and commented on through the Documents, Sheets and Slides routes with kind: "video", and its media are Drive files. These routes add what Video keeps beside a project. They're under /v1/orgs/:orgId/video (an organization's projects) and /v1/me/video (your own); an organization's need a plan with Documents, Sheets, Slides and Video.

Proxies and mixdowns upload like Drive's files: POST files/:fileId/proxies answers the part size and links for the first parts; PUT each part's bytes to its link, ask …/parts for more links, then …/complete. They're stored with the project, count against its space's storage, can be read by anyone who can read the project (GET /v1/orgs/:orgId/office/files/:fileId/media/:mediaId), and go when it's deleted. Making a copy of a project leaves its proxies behind.

Transcriptions run on Amazon Transcribe in the platform's home region and take a minute or more. The caption track arrives in the project by itself, so people with it open see it appear; GET …/transcriptions/:transcriptionId reports progress. Each person has a daily allowance of minutes (video.transcribeMinutesPerDay).

Times are in flicks, 1/705,600,000 of a second, as in the project itself.

Changes need drive:write as well as edit access to the project.

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:fileId`	File id, as returned when the upload was created.

Response 200

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

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:fileId`	File id, as returned when the upload was created.

Request body

Field	Type	Required	Notes
`mediaRef`	`string`	No	up to 64 characters
`name`	`string`	Yes	1–255 characters
`size`	`integer`	Yes	≥ 1
`mime`	`string`	Yes	up to 100 characters
`purpose`	`"proxy" \| "audio"`	No

Response 201

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

Errors

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

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

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

Auth: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`: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

Field	Type	Required	Notes
`parts`	`integer[]`	Yes	1–100 items; each 1–10000

Response 200

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

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`: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.

Response 200

{
  mediaId: string
  size: number
  mime: string
}

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`: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.

Response 200

{
  deleted: boolean
}

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:fileId`	File id, as returned when the upload was created.

Response 200

{
  mediaId: string
  size: number
  mime: string
}

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:fileId`	File id, as returned when the upload was created.

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
  }
}

Errors

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

`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: user access token or platform agent key · Scope: drive:read

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

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
  }
}

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`:fileId`	File id, as returned when the upload was created.

Response 200

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

Errors

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

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

Auth: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`:fileId`	File id, as returned when the upload was created.

Request body

Field	Type	Required	Notes
`mediaRef`	`string`	No	up to 64 characters
`name`	`string`	Yes	1–255 characters
`size`	`integer`	Yes	≥ 1
`mime`	`string`	Yes	up to 100 characters
`purpose`	`"proxy" \| "audio"`	No

Response 201

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

Errors

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

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

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

Auth: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`: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

Field	Type	Required	Notes
`parts`	`integer[]`	Yes	1–100 items; each 1–10000

Response 200

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

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`: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.

Response 200

{
  mediaId: string
  size: number
  mime: string
}

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`: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.

Response 200

{
  deleted: boolean
}

Errors

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

`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: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`:fileId`	File id, as returned when the upload was created.

Response 200

{
  mediaId: string
  size: number
  mime: string
}

Errors

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

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

Auth: user access token or platform agent key · Scope: drive:read

Path parameter	Description
`:fileId`	File id, as returned when the upload was created.

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
  }
}

Errors

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

`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: user access token or platform agent key · Scope: drive:read

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

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
  }
}

Errors

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

`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: user access token or platform agent 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
  }
}

Errors

Status	Message
`403`	Video's settings are for people signed in.

Video

On this page