Upload de Arquivos via API

O Kinescope permite fazer upload de vídeos via API. Isso permite enviar arquivos diretamente para projetos e pastas, controlar o acesso a links de upload e manter seu token de API oculto dos usuários de aplicações cliente.

Para quem é este artigo

• Desenvolvedores — precisam integrar o upload de vídeos em seus sistemas
• Administradores de plataforma — precisam automatizar o upload de conteúdo
• Engenheiros DevOps — precisam configurar uploads em massa de vídeos

Quando você precisa de upload via API

O upload via API é útil se:

• É necessária integração com seu sistema — upload automático de vídeos da sua aplicação
• Controle de acesso é necessário — você quer gerenciar quem pode fazer upload de arquivos
• Segurança — o token de API fica no servidor, não na aplicação cliente
• Upload em massa — você precisa fazer upload de muitos vídeos de um CSV ou outra fonte

Métodos de upload

O Kinescope suporta três métodos de upload:

1. Criando um link de upload — obtenha um link que pode ser usado para upload (conveniente para aplicações cliente)
2. Upload em uma única solicitação — envie o arquivo e os metadados em uma solicitação
3. Upload por URL — forneça um link para o arquivo de vídeo, o Kinescope faz o download por conta própria

Para arquivos grandes: Recomendamos usar o protocolo Tus para upload de arquivos grandes em partes. Veja o exemplo de implementação aqui .

Preparação: obtendo o ID do projeto ou pasta

Antes de fazer upload de um vídeo, você precisa selecionar um projeto ou pasta para o arquivo. O ID do projeto ou pasta pode ser obtido via API:

Antes de começar: Se esta é sua primeira vez usando a Kinescope API, recomendamos revisar as regras gerais da API — elas cobrem autorização, formato de token (UUID), paginação e tratamento de erros.

Obtenha a lista de projetos:

curl --location 'https://api.kinescope.io/v1/projects' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}'

A resposta conterá uma lista de projetos com seus IDs. Use o id da resposta para obter a lista de pastas em um projeto específico.

Paginação e ordenação: Listas de projetos e pastas suportam paginação (page, per_page) e ordenação (order). Veja mais nas regras gerais da API .

Obtenha a lista de pastas em um projeto:

curl --location 'https://api.kinescope.io/v1/projects/${PROJECT_ID}/folders' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}'

Substitua ${PROJECT_ID} pelo ID do projeto da solicitação anterior.

A resposta conterá uma lista de pastas com seus IDs. O ID do projeto ou pasta pode ser usado no parâmetro parent_id ao fazer upload do vídeo.

Vídeo sobre configuração e trabalho com projetos:

Vídeo sobre configuração e trabalho com pastas:

Método 1: Criando um link de upload

Este método é conveniente quando você precisa permitir o upload diretamente por meio de uma aplicação cliente. Você obtém um link que pode ser passado para o cliente para fazer upload do arquivo.

Exemplo de solicitação:

curl --location --request POST 'https://uploader.kinescope.io/v2/init' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}' \
--data-raw '{
    "filesize": 10485760,
    "type": "video",
    "title": "Meu Vídeo",
    "parent_id": "e51e55a1-7615-493e-9055-10ac9cc44ccd",
    "filename": "video.mp4",
    "description": "Descrição do vídeo",
    "client_ip": "11.22.33.44"
}'

Resposta:

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

O que fazer a seguir? Use o endpoint da resposta para fazer upload do arquivo (veja “Fazendo upload de um arquivo usando o link recebido” abaixo).

Parâmetros da solicitação

Parâmetros comuns:

Parâmetros para o tipo video:

Parâmetros para o tipo attachment:

Fazendo upload de um arquivo usando o link recebido

Após obter o link (endpoint), faça upload do arquivo via uma solicitação POST. O mesmo link pode ser usado para fazer upload de arquivos grandes em partes via protocolo Tus .

Exemplo de solicitação:

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

Método 2: Upload de vídeo em uma única solicitação

Neste caso, os metadados são passados nos cabeçalhos da solicitação e o arquivo de vídeo no corpo. Isso é adequado para arquivos pequenos ou quando você precisa fazer upload de um arquivo e especificar metadados imediatamente.

Exemplo de solicitação:

curl --location --request POST 'https://uploader.kinescope.io/v2/video' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}' \
--header 'X-Parent-ID: ${PARENT_ID}' \
--header 'X-Video-Title: ${TITLE}' \
--header 'X-Video-Description: ${DESCRIPTION}' \
--header 'Content-Type: video/mp4' \
--data-binary '@/caminho/para/video.mp4'

Cabeçalhos da solicitação:

Método 3: Upload de vídeo por URL

Você pode usar um link direto para um arquivo de vídeo ou uma URL do YouTube (por exemplo, https://www.youtube.com/watch?v=UTgSnM3mA-4 ou https://youtu.be/UTgSnM3mA-4). O Kinescope fará o download do arquivo a partir do link fornecido por conta própria.

Exemplo de solicitação:

curl --location --request POST 'https://uploader.kinescope.io/v2/video' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}' \
--header 'X-Parent-ID: ${PARENT_ID}' \
--header 'X-Video-Title: ${TITLE}' \
--header 'X-Video-URL: ${URL_DO_ARQUIVO_DE_VIDEO}'

Cabeçalhos da solicitação:

Links diretos para posters

Após fazer upload de um vídeo, você pode obter links diretos para posters (imagens de prévia). Tamanhos disponíveis: xs, sm, md, lg.

Formato do link:

https://kinescope.io/{video_id}/poster.{jpg|webp}
https://kinescope.io/{video_id}/poster/{size}.{jpg|webp}

Exemplos:

https://kinescope.io/2WFmbHsNz1W72DL9DGz2ps/poster.jpg
https://kinescope.io/2WFmbHsNz1W72DL9DGz2ps/poster/md.webp

Exemplo: Importação em massa via CSV

Se você precisar fazer upload de muitos vídeos de um arquivo CSV, você pode usar um script bash simples com curl. Isso é mais simples do que escrever uma aplicação completa.

Importante: O arquivo CSV deve ter colunas chamadas url e title.

Exemplo de arquivo CSV:

url,title
https://example.com/video1.mp4,Título do Vídeo 1
https://example.com/video2.mp4,Título do Vídeo 2

Solicitação única (exemplo)

Para fazer upload de um vídeo por URL, use esta solicitação curl:

curl --location --request POST 'https://uploader.kinescope.io/v2/video' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}' \
--header 'X-Video-URL: https://example.com/video1.mp4' \
--header 'X-Video-Title: Título do Vídeo 1' \
--header 'X-Parent-ID: ${PARENT_ID}'

Script bash para importação em massa

Aqui está um script simples que lê um CSV e faz upload de todos os vídeos:

#!/bin/bash

# Configurações
KINESCOPE_API_TOKEN="seu_token_de_api"
PARENT_ID="id_do_projeto_ou_pasta"
CSV_FILE="videos.csv"

# Verificar se o arquivo existe
if [ ! -f "$CSV_FILE" ]; then
    echo "Erro: arquivo $CSV_FILE não encontrado"
    exit 1
fi

# Pular o cabeçalho CSV (primeira linha)
tail -n +2 "$CSV_FILE" | while IFS=',' read -r url title; do
    url=$(echo "$url" | tr -d ' "')
    title=$(echo "$title" | tr -d ' "')
    
    if [ -z "$url" ] || [ -z "$title" ]; then
        continue
    fi
    
    echo "Fazendo upload: $title ($url)"
    
    response=$(curl -s -w "\n%{http_code}" --location --request POST 'https://uploader.kinescope.io/v2/video' \
        --header "Authorization: Bearer $KINESCOPE_API_TOKEN" \
        --header "X-Video-URL: $url" \
        --header "X-Video-Title: $title" \
        --header "X-Parent-ID: $PARENT_ID")
    
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')
    
    if [ "$http_code" -eq 200 ] || [ "$http_code" -eq 201 ]; then
        video_id=$(echo "$body" | grep -o '"id":"[^"]*"' | cut -d'"' -f4)
        echo "  ✓ Upload realizado com sucesso. ID: $video_id"
    else
        echo "  ✗ Erro (HTTP $http_code): $body"
    fi
    
    echo ""
done

echo "Importação concluída"

Como usar:

1. Salve o script em um arquivo (por exemplo, import.sh)
2. Torne-o executável: chmod +x import.sh
3. Defina seu token de API e ID de projeto/pasta nas variáveis
4. Execute: ./import.sh

Para desenvolvedores: Se você precisar de lógica mais complexa (tratamento de erros, uploads paralelos, mapeamento de armazenamento), use Python, Node.js ou outra linguagem. Mas para casos simples, um script bash com curl é a opção mais rápida.

Qual método escolher?

• Criando um link de upload — se você precisar permitir que clientes façam upload de arquivos diretamente
• Upload em uma única solicitação — para arquivos pequenos ou quando você precisa especificar todos os metadados imediatamente
• Upload por URL — se os arquivos já estiverem na internet (YouTube, seu armazenamento, etc.)

Pronto! Agora você pode fazer upload de vídeos via Kinescope API usando qualquer método conveniente.

O que fazer a seguir?

1. Exemplo de implementação do protocolo Tus — upload de arquivos grandes em partes
2. Regras gerais da API — autorização e formato de solicitação
3. Kinescope API — documentação completa da API

Ainda tem dúvidas? Escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudar!