API de vídeo - Base de conhecimento

Videos

O objeto vídeo

Campo	Tipo	Descrição
id	string	Identificador único do objeto.
project_id	string
folder_id	string
version	number
title	string
description	string
status	enum	Valores possíveis: pending, uploading, pre-processing, processing, aborted, done, error
progress	number	Progresso do processamento do vídeo
duration	number	Duração do vídeo em segundos
assets	[]Asset
has_audio	bool	Indica se o vídeo tem áudio.
audio_tracks	[]AudioTrack	Faixas de áudio disponíveis para download (`id`, `language`, `label`, `file_size`, `filetype`, `original_name`, `download_link`). Ausente quando o vídeo não tem faixas de áudio.
chapters	Chapters
privacy_type	enum	Valores possíveis: anywhere, nowhere, custom
privacy_domains	[]string	Domínios na lista de permissões
poster	Poster
additional_materials	[]AdditionalMaterial
additional_materials_enabled	bool
annotation_text_enabled	bool
annotation_video_enabled	bool
created_at	datetime
updated_at	datetime
play_link	string	Link para o player
embed_link	string	Link para incorporar o player
subtitles		Subtitles
subtitles_enabled	boolean	Exibir/ocultar legendas no player
hls_link	string	Link para o manifesto HLS

Concatenar vídeo

POST https://api.kinescope.io/v1/videos/:video_id/concat

Junta o vídeo de origem com um ou mais vídeos em um novo vídeo. O vídeo original fica intacto, e o conteúdo combinado vai para um vídeo novo.

Request body (json)

{
  "prepend": [
    {
      "video_id": "<UUID>"
    }
  ],
  "append": [
    {
      "video_id": "<UUID>"
    }
  ],
  "replace": false
}

curl -X POST \
  'https://api.kinescope.io/v1/videos/:video_id/concat' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "prepend": [
    {
      "video_id": "<UUID>"
    }
  ],
  "append": [
    {
      "video_id": "<UUID>"
    }
  ],
  "replace": false
}'

Copiar vídeo

POST https://api.kinescope.io/v1/videos/:video_id/copy

Cria uma cópia completa do vídeo e, se você quiser, coloca a cópia em outro projeto ou pasta.

Request body (json)

{
  "parent_id": "<UUID>"
}

Cortar vídeo

POST https://api.kinescope.io/v1/videos/:video_id/cut

Corta o vídeo para o intervalo de tempo indicado. O resultado é gravado no mesmo ID de vídeo; os bytes originais são substituídos.

Cria um vídeo com corte de tempo ou de quadro.

Campo	Tipo	Descrição
project_id	string	não obrigatório
folder_id	string	não obrigatório
title	string	não obrigatório
description	string	não obrigatório
crop	crop_object	w, h — largura, altura; x, y — canto superior esquerdo
trim	[]trim_object	start — hora de início; length — duração do vídeo

Request body (json)

{
  "crop": {
    "w": 300,
    "h": 200,
    "x": 100,
    "y": 80,
    "quality": "360p"
  },
  "trim": [
    {
      "start": 6,
      "length": 2
    },
    {
      "start": 1,
      "length": 2
    }
  ]
}

curl -X POST \
  'https://api.kinescope.io/v1/videos/:video_id/cut' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "crop": {
    "w": 300,
    "h": 200,
    "x": 100,
    "y": 80,
    "quality": "360p"
  },
  "trim": [
    {
      "start": 6,
      "length": 2
    },
    {
      "start": 1,
      "length": 2
    }
  ]
}'

Lista de vídeos

GET https://api.kinescope.io/v1/videos

Retorna a lista de vídeos. Os resultados são paginados e podem ser filtrados por parâmetros de consulta.

Responses

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 1,
      "total": 10
    },
    "order": {
      "created_at": "desc",
      "title": "asc"
    }
  },
  "data": [
    {
      "id": "vKSxQyZScoQfP29oothREi",
      "project_id": "mNFQz2wYTBhLkPBCo9oS8m",
      "folder_id": null,
      "version": 0,
      "title": "sample_video",
      "description": "",
      "status": "uploading",
      "progress": 100,
      "duration": 0,
      "assets": [],
      "chapters": {
        "items": [],
        "enabled": false,
        "show_on_load": false
      },
      "privacy_type": "anywhere",
      "privacy_domains": [],
      "poster": null,
      "additional_materials": null,
      "additional_materials_enabled": false,
      "play_link": "https://kinescope.io/199511994",
      "embed_link": "https://kinescope.io/embed/199511994",
      "created_at": "2020-08-31T09:03:00.106436Z",
      "updated_at": null,
      "subtitles": [],
      "subtitles_enabled": false,
      "hls_link": "https://kinescope.io/199511994/master.m3u8"
    }
  ]
}

curl -X GET \
  'https://api.kinescope.io/v1/videos?page=1&per_page=1&order=created_at.desc,title.asc&project_id=<UUID>&status[]=uploading&video_ids[]=<UUID>&q=sample' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Obter vídeo

GET https://api.kinescope.io/v1/videos/:video_id

Retorna os dados de um vídeo pelo seu identificador único.

Responses

{
  "data": {
    "id": "<UUID>",
    "project_id": "<UUID>",
    "folder_id": null,
    "player_id": "<UUID>",
    "version": 1,
    "title": " Encrypted, saved (2024.09.08 13:35)",
    "subtitle": "",
    "description": "",
    "status": "done",
    "progress": 0,
    "duration": 66.00001,
    "assets": [
      {
        "id": "<UUID>",
        "video_id": "<UUID>",
        "original_name": "original.ts",
        "file_size": 4862244,
        "md5": "a05d6c66884dc7f8c5136b6c9d95fef7",
        "filetype": "ts",
        "quality": "original",
        "resolution": "1920x1080",
        "created_at": "2024-09-08T10:35:17.087638Z",
        "url": "https://kinescopecdn.net/<UUID>/videos/<UUID>/assets/<UUID>/original.mp4?expires=<EXPIRES>&sign=<SIGNATURE>",
        "download_link": "https://s3.kinescope.io/<UUID>/videos/<UUID>/mp4/original.ts?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<CREDENTIAL>"
      },
      {
        "id": "<UUID>",
        "video_id": "<UUID>",
        "original_name": "1080p.mp4",
        "file_size": 4292636,
        "filetype": "mp4",
        "quality": "1080p",
        "resolution": "1920x1080",
        "created_at": "2024-09-08T10:35:30.549646Z",
        "download_link": ""
      },
      {
        "id": "<UUID>",
        "video_id": "<UUID>",
        "original_name": "720p.mp4",
        "file_size": 3217594,
        "filetype": "mp4",
        "quality": "720p",
        "resolution": "1280x720",
        "created_at": "2024-09-08T10:35:30.549646Z",
        "download_link": ""
      },
      {
        "id": "<UUID>",
        "video_id": "<UUID>",
        "original_name": "480p.mp4",
        "file_size": 2031032,
        "filetype": "mp4",
        "quality": "480p",
        "resolution": "852x480",
        "created_at": "2024-09-08T10:35:30.549646Z",
        "download_link": ""
      },
      {
        "id": "<UUID>",
        "video_id": "<UUID>",
        "original_name": "360p.mp4",
        "file_size": 1451443,
        "filetype": "mp4",
        "quality": "360p",
        "resolution": "640x360",
        "created_at": "2024-09-08T10:35:30.549646Z",
        "download_link": ""
      }
    ],
    "has_audio": true,
    "audio_tracks": [
      {
        "id": "<UUID>",
        "language": "en",
        "label": "English",
        "file_size": 4292636,
        "filetype": "mp4",
        "original_name": "audio_en.mp4",
        "download_link": "https://s3.kinescope.io/<UUID>/videos/<UUID>/audio/<UUID>.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<CREDENTIAL>"
      },
      {
        "id": "<UUID>",
        "language": "ru",
        "label": "Русский",
        "file_size": 4185220,
        "filetype": "mp4",
        "original_name": "audio_ru.mp4",
        "download_link": "https://s3.kinescope.io/<UUID>/videos/<UUID>/audio/<UUID>.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<CREDENTIAL>"
      }
    ],
    "chapters": {
      "items": [],
      "enabled": false
    },
    "privacy_type": "anywhere",
    "privacy_domains": [],
    "privacy_email_domains": [],
    "privacy_share": {},
    "tags": [],
    "poster": {
      "id": "<UUID>",
      "type": "image",
      "media_id": "<UUID>",
      "status": "done",
      "active": true,
      "original": "https://kinescopecdn.net/<UUID>/posters/<UUID>/<UUID>.jpg",
      "md": "https://kinescopecdn.net/<UUID>/posters/<UUID>/md/<UUID>.jpg",
      "sm": "https://kinescopecdn.net/<UUID>/posters/<UUID>/sm/<UUID>.jpg",
      "xs": "https://kinescopecdn.net/<UUID>/posters/<UUID>/xs/<UUID>.jpg",
      "from_time": 0,
      "to_time": 0
    },
    "additional_materials": [],
    "additional_materials_enabled": false,
    "annotation_text_enabled": false,
    "annotation_video_enabled": false,
    "play_link": "https://kinescope.io/vN1xLXadcCk94aCuZHR5i2",
    "embed_link": "https://kinescope.io/embed/vN1xLXadcCk94aCuZHR5i2",
    "created_at": "2024-09-08T10:35:11.674333Z",
    "updated_at": "2026-03-05T14:04:37.150678Z",
    "subtitles": [],
    "subtitles_enabled": false,
    "hls_link": "https://kinescope.io/vN1xLXadcCk94aCuZHR5i2/master.m3u8",
    "chat_preview": false,
    "chat_inside_player": "",
    "chat_expand_on_load": false,
    "meta": {
      "event_id": "<UUID>",
      "stream_id": "<UUID>"
    }
  }
}

{
  "error": {
    "code": 400404,
    "message": "not found"
  }
}

Mover vídeo para outro projeto e pasta

PUT https://api.kinescope.io/v1/videos/:video_id/move

Move o vídeo para outro projeto e/ou outra pasta. O ID do vídeo não muda.

Request body (json)

{
  "project_id": "3kAyiWTAZQKKZxg1GfjKvS",
  "folder_id": "2MxB8wx35jHQjhCPczBamu"
}

curl -X PUT \
  'https://api.kinescope.io/v1/videos/:video_id/move' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": "3kAyiWTAZQKKZxg1GfjKvS",
  "folder_id": "2MxB8wx35jHQjhCPczBamu"
}'

Atualizar capítulos

PUT https://api.kinescope.io/v1/videos/:video_id/chapters

Substitui os marcadores de capítulo do vídeo pela lista enviada. Envie um array vazio para remover todos os capítulos.

Request body (json)

{
  "items": [
    {
      "time": 10000,
      "title": "Chapter at 10sec"
    }
  ],
  "enabled": true
}

Responses

{
  "data": {
    "items": [
      {
        "time": 10000,
        "title": "Chapter at 10sec"
      }
    ],
    "enabled": true
  }
}

curl -X PUT \
  'https://api.kinescope.io/v1/videos/:video_id/chapters' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "time": 10000,
      "title": "Chapter at 10sec"
    }
  ],
  "enabled": true
}'

Atualizar vídeo

PATCH https://api.kinescope.io/v1/videos/:video_id

Atualiza o vídeo indicado. Só os campos enviados no corpo da requisição são alterados; os demais ficam como estão.

Esta requisição atualiza somente os campos enviados.

Campos que podem ser atualizados: title, description, privacy_type, privacy_domains, additional_materials_enabled

Request body (json)

{
  "title": "New title",
  "description": "New description",
  "privacy_type": "custom",
  "privacy_domains": [
    "example.com"
  ],
  "additional_materials_enabled": false,
  "tags": [
    "tag 1",
    "tag 2",
    "tag 3"
  ]
}

Responses

{
  "data": {
    "id": "iuFPEzdC2Jtf8aCcvMJQ8h",
    "workspace_id": "s8vL2Zr3CxCj1A8HmxoGhp",
    "project_id": "hfHfAgq4g2nxxtg8DQ3Twi",
    "folder_id": null,
    "storage_id": "mucjva43n3sLsw5YRwsZYS",
    "short_id": 199511990,
    "version": 0,
    "title": "New title",
    "description": "New description",
    "status": "done",
    "progress": 0,
    "duration": 179.305,
    "assets": [
      {
        "id": "i7r58w3Lt3bPoPyX27tprT",
        "video_id": "iuFPEzdC2Jtf8aCcvMJQ8h",
        "original_name": "original.mp4",
        "file_size": 5603249,
        "filetype": "QuickTime / MOV",
        "quality": "original",
        "resolution": "320x240",
        "created_at": "2020-08-30T16:10:08.091561Z",
        "updated_at": null,
        "deleted_at": null
      },
      {
        "id": "kdwSHkB2e1AH8veDLuCnUP",
        "video_id": "iuFPEzdC2Jtf8aCcvMJQ8h",
        "original_name": "360p.mp4",
        "file_size": 4196287,
        "filetype": "QuickTime / MOV",
        "quality": "360p",
        "resolution": "320x240",
        "created_at": "2020-08-30T16:10:14.087606Z",
        "updated_at": null,
        "deleted_at": null
      }
    ],
    "chapters": {
      "items": [],
      "enabled": false,
      "show_on_load": false
    },
    "privacy_type": "custom",
    "privacy_domains": [
      "example.com"
    ],
    "poster": {
      "id": "eHqAqKuMi4JTsAoMvf5GRs",
      "video_id": "iuFPEzdC2Jtf8aCcvMJQ8h",
      "storage_id": "mucjva43n3sLsw5YRwsZYS"
    },
    "additional_materials": [],
    "additional_materials_enabled": false,
    "created_at": "2020-08-30T16:10:05.702154Z",
    "updated_at": null,
    "deleted_at": null
  }
}

curl -X PATCH \
  'https://api.kinescope.io/v1/videos/:video_id' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "New title",
  "description": "New description",
  "privacy_type": "custom",
  "privacy_domains": [
    "example.com"
  ],
  "additional_materials_enabled": false,
  "tags": [
    "tag 1",
    "tag 2",
    "tag 3"
  ]
}'

Excluir vídeo

DELETE https://api.kinescope.io/v1/videos/:video_id

Exclui o vídeo permanentemente. A ação não pode ser desfeita.

Responses

{
  "data": {
    "success": true
  }
}

Videos

Criar sessão de envio

POST https://uploader.kinescope.io/v2/init

Cria uma sessão de envio e devolve o endereço para onde o arquivo é enviado. Use quando o arquivo for grande, a rede não for confiável ou o envio acontecer em um navegador ao qual você não quer entregar o token do API: o próprio endereço autoriza o envio.

O endpoint devolvido é roteado por geografia — https://eu-ams-uploader-1.kinescope.io/v2/upload/… — então mande o arquivo exatamente para lá, não remonte a URL a partir do host base.

Corpo

Parâmetro	Tipo	Descrição
`type`	`enum`	Obrigatório. `video`, `attachment` ou `replace`.
`parent_id`	`uuid`	Obrigatório para `type: video`. Projeto ou pasta onde o vídeo vai parar. Obtenha em `GET /v1/projects` ou `GET /v1/projects/:project_id/folders`.
`title`	`string`	Obrigatório para `type: video`. Título do vídeo.
`video_id`	`uuid`	Obrigatório para `type: attachment`. O vídeo ao qual o material é anexado.
`filesize`	`integer`	Obrigatório para tus. Tamanho do arquivo em bytes. Alimenta o indicador de progresso.
`filename`	`string`	Nome do arquivo. Informativo.
`subtitle`	`string`	Subtítulo do vídeo.
`description`	`string`	Descrição do vídeo.
`client_ip`	`string`	IP do cliente final. Escolhe o servidor de envio mais próximo.
`preview`	`object`	Cria um clipe de prévia acessível em `https://kinescope.io/{video_id}/preview`. Campos: `start` e `length` em segundos, `quality` — `360p`, `480p`, `720p` ou `1080p`.

O conjunto de parâmetros de type: replace não está descrito no guia e precisa de confirmação.

Request body (json)

{
  "type": "video",
  "parent_id": "e51e55a1-7615-493e-9055-10ac9cc44ccd",
  "title": "Product demo",
  "filename": "demo.mp4",
  "filesize": 48622440
}

Responses

{
  "data": {
    "id": "7127f2d7-0e96-40d0-9a03-2e987c096466",
    "endpoint": "https://eu-ams-uploader-1.kinescope.io/v2/upload/0966958f-638b-4aab-bf4a-7f9860a57a93"
  }
}

curl -X POST \
  'https://uploader.kinescope.io/v2/init' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "video",
  "parent_id": "e51e55a1-7615-493e-9055-10ac9cc44ccd",
  "title": "Product demo",
  "filename": "demo.mp4",
  "filesize": 48622440
}'

Passo 2: enviar o arquivo para o endereço devolvido

O endereço de data.endpoint aceita tanto um POST simples com o arquivo no corpo quanto o protocolo tus. O token de acesso não é enviado nesta etapa — o próprio endereço é a permissão.

curl -X POST \
  'https://eu-ams-uploader-1.kinescope.io/v2/upload/0966958f-638b-4aab-bf4a-7f9860a57a93' \
  --data-binary '@demo.mp4'

Para envios retomáveis use uma biblioteca cliente de tus: ela manda HEAD para ler o Upload-Offset atual e continua com PATCH a partir daquele byte, recebendo 204 No Content com o novo deslocamento após cada trecho. Um POST simples não retoma — depois de uma queda o envio recomeça do zero.

Por quanto tempo o endereço devolvido continua válido não está documentado e precisa de confirmação. O limite a partir do qual o tus passa a ser obrigatório também não está documentado.

Enviar vídeo

POST https://uploader.kinescope.io/v2/video

Envia um vídeo em uma única requisição. Os metadados vão nos cabeçalhos e o arquivo no corpo — ou, com o cabeçalho X-Video-URL, o corpo fica vazio e o Kinescope baixa o arquivo sozinho.

Use para arquivos pequenos em conexão estável e para importar do seu próprio armazenamento. Para arquivos grandes use POST /v2/init e tus: este endpoint não retoma, e uma conexão interrompida significa começar de novo.

Cabeçalhos

Parâmetro	Tipo	Descrição
`X-Parent-ID`	`uuid`	Obrigatório. Projeto ou pasta onde o vídeo vai parar.
`X-Video-Title`	`string`	Obrigatório. Título do vídeo.
`X-Video-URL`	`string`	Obrigatório no envio por URL. Link direto para o arquivo ou endereço do YouTube na forma `https://www.youtube.com/watch?v=…` ou `https://youtu.be/…`. Com este cabeçalho o corpo da requisição fica vazio.
`X-Video-Description`	`string`	Descrição do vídeo.
`X-File-Name`	`string`	Nome do arquivo.
`X-Replace-Video-ID`	`uuid`	Vídeo a ser substituído. Se o identificador, os metadados e os links sobrevivem à substituição não está documentado e precisa de confirmação.
`X-Video-Trim`	`json`	Corte no envio, valores em segundos: `{"start": 1, "length": 2}`. Sem `length`, o vídeo é cortado de `start` até o fim.
`Content-Type`	`string`	Tipo dos dados no corpo, por exemplo `video/mp4`.

X-Poster-URL aparece na versão anterior desta página, mas não no guia para desenvolvedores: seu suporte precisa de confirmação.

O formato do corpo é descrito como multipart na versão anterior desta página, enquanto o guia envia o arquivo como corpo bruto. O tamanho máximo de arquivo deste endpoint não é publicado. Ambos precisam de confirmação.

Responses

{
  "data": {
    "id": "8d1c4b7e-2f39-4a06-b5c8-71e0a9d3f462",
    "project_id": "3f2a9c14-7b6d-4e58-9a21-0c5e8d47b193",
    "title": "Product demo",
    "status": "uploading",
    "progress": 0,
    "play_link": "https://kinescope.io/bK3mQx7ZtNvRs2WdYpLc9F"
  }
}

curl -X POST \
  'https://uploader.kinescope.io/v2/video' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'X-Parent-ID: e51e55a1-7615-493e-9055-10ac9cc44ccd' \
  -H 'X-Video-Title: Product demo' \
  -H 'X-File-Name: demo.mp4' \
  -H 'Content-Type: video/mp4' \
  --data-binary '@demo.mp4'

curl -X POST \
  'https://uploader.kinescope.io/v2/video' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'X-Parent-ID: e51e55a1-7615-493e-9055-10ac9cc44ccd' \
  -H 'X-Video-Title: Product demo' \
  -H 'X-Video-URL: https://example.com/media/demo.mp4'

Depois do envio

Um envio concluído não significa um vídeo pronto. Consulte GET /v1/videos/{video_id} pelo identificador devolvido na primeira etapa, no máximo uma vez a cada 5 segundos, ou assine o webhook media.update.status. Os status terminais são done, error e aborted; progress não é sinal de prontidão.

Se o arquivo em X-Video-URL estiver inacessível, o vídeo termina em status: error e o motivo chega no payload do webhook.

Repetir um POST depois de um tempo esgotado cria um segundo vídeo: Idempotency-Key não é suportado. Antes de repetir, procure o vídeo com GET /v1/videos filtrando por projeto e título, ou substitua a tentativa que falhou por meio de X-Replace-Video-ID.