# 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](https://tus.io) para upload de arquivos grandes em partes. Veja o exemplo de implementação [aqui](https://docs-br.kinescope.com/developer-guides/tus-protocol-implementation/).

## **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](https://docs-br.kinescope.com/developer-guides/api-general-rules/) — elas cobrem autorização, formato de token (UUID), paginação e tratamento de erros.

**Obtenha a lista de projetos:**

```bash
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](https://docs-br.kinescope.com/developer-guides/api-general-rules/#pagination).

**Obtenha a lista de pastas em um projeto:**

```bash
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:

[Видео Kinescope]

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

[Видео Kinescope]

## **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:**

```bash
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:**

```json
{
  "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:**

| Campo | Tipo | Descrição |
|---|---|---|
| `type` | string | **Obrigatório.** Valores: `video`, `attachment`, `replace` |
| `client_ip` | string | Endereço IP do cliente. Determina o servidor de upload mais próximo |
| `filesize` | int | **Obrigatório para Tus.** Tamanho do arquivo em bytes. Usado para exibir o progresso |

**Parâmetros para o tipo `video`:**

| Campo | Tipo | Descrição |
|---|---|---|
| `parent_id` | uuid | **Obrigatório.** ID do projeto ou pasta para upload do vídeo |
| `title` | string | **Obrigatório.** Título do vídeo |
| `subtitle` | string | Subtítulo do vídeo |
| `description` | string | Descrição do vídeo |
| `filename` | string | Nome do arquivo (campo informativo) |
| `preview` | object | Após passar este parâmetro, um clipe .mp4 do vídeo é criado, acessível em: `https://kinescope.io/${video_id}/preview`<br>Exemplo:<br>`{`<br>`  start: 0,      // Tempo de início em segundos`<br>`  length: 5,     // Duração do clipe em segundos`<br>`  quality: '720p' // Resolução do clipe (360p, 480p, 720p, 1080p)`<br>`}` |

**Parâmetros para o tipo `attachment`:**

| Campo | Tipo | Descrição |
|---|---|---|
| `video_id` | uuid | ID do vídeo ao qual o material complementar está sendo enviado |

## **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](https://tus.io).

**Exemplo de solicitação:**

```bash
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:**

```bash
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:**

| Campo | Tipo | Descrição |
|---|---|---|
| `X-Parent-ID` | uuid | **Obrigatório.** ID do projeto ou pasta para upload |
| `X-Video-Title` | string | **Obrigatório.** Título do vídeo |
| `X-Video-Description` | string | Descrição do vídeo |
| `X-File-Name` | string | Nome do arquivo |
| `X-Replace-Video-ID` | uuid | ID do vídeo a ser substituído |
| `Content-Type` | string | Tipo de dados passados no corpo da solicitação |
| `X-Video-Trim` | json | Dados para corte do vídeo **em segundos**, por exemplo: `{"start": 1, "length": 2}`. Se o parâmetro `length` não for passado, o vídeo será cortado do `start` especificado até o final |

## **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:**

```bash
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:**

| Campo | Tipo | Descrição |
|---|---|---|
| `X-Video-URL` | string | **Obrigatório.** Link direto para o arquivo de vídeo ou URL do YouTube |
| `X-Parent-ID` | uuid | **Obrigatório.** ID do projeto ou pasta para upload |
| `X-Video-Title` | string | **Obrigatório.** Título do vídeo |
| `X-Video-Description` | string | Descrição do vídeo |

## **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:**

```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:

```bash
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:

```bash
#!/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](https://docs-br.kinescope.com/developer-guides/tus-protocol-implementation/)** — upload de arquivos grandes em partes
2. **[Regras gerais da API](https://docs-br.kinescope.com/developer-guides/api-general-rules/)** — autorização e formato de solicitação
3. **[Referência da API](https://docs-br.kinescope.com/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!