Carregar vídeos

Para carregar vídeos, envia um pedido PUT para o endpoint /videos/upload para criares um novo objeto de vídeo. Vais receber uma resposta com um URL S3 assinado para carregares o ficheiro de vídeo.

Criar um vídeo exige a permissão videos.create. Definir visibility como public também exige videos.publish. Sem publish, o vídeo é criado como private. Consulta Autenticação.

title é obrigatório. É aparado e cortado para 100 caracteres. Uma atualização permite 150 caracteres. Consulta Atualizar um vídeo.

O corpo JSON também aceita:

Campo	Notas
`description`	Máximo de 2000 caracteres.
`visibility`	`public` exige `videos.publish`. Caso contrário, o vídeo é gravado como `private`.
`categories`	No máximo 10 ids. Os ids desconhecidos são descartados. Uma chave com âmbito que não recebe categorias recebe as categorias do âmbito, até 10.
`tags`	No máximo 20 ids. Os ids desconhecidos são descartados.
`language`	Locale do idioma falado, por exemplo `de-DE`. Obrigatório quando `autoTranscribe` é `true`.
`autoTranscribe`	Inicia a transcrição por IA após a codificação.
`customMetadata`	Objeto plano de chave-valor. Consulta o objeto de vídeo.
`duration`	Indicação opcional, em segundos. A codificação sobrescreve-a.
`fps`	Indicação opcional. A codificação sobrescreve-a.
`orientation`	`landscape` ou `portrait`. A codificação sobrescreve-o.
`useMultipart`	Devolve identificadores de multipart upload em vez de `signedUrl`.

O corpo JSON não tem o campo mimeType. Envia o tipo MIME do ficheiro no cabeçalho Content-Type do carregamento para o URL assinado, no passo seguinte.

Criar objeto de vídeo

CURL


curl -X PUT https://app.ignitevideo.cloud/api/videos/upload \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Your video title", "visibility": "private" | "public"}'

JavaScript / Node.js


const data = {
  "title": "Your video title", // trimmed, max 100 characters
  "visibility": "private" | "public", // optional
  "description": "Optional description",
  "categories": ["category-id", "..."], // optional
  "tags": ["tag-id", "..."], // optional
  "customMetadata": { "externalId": "celum-123" }, // optional
  "duration": 90, // optional, seconds
  "fps": 25, // optional
  "orientation": "landscape" // optional: "landscape" | "portrait"
}
const response = await fetch(`https://app.ignitevideo.cloud/api/videos/upload`, {
method: 'PUT',
body: JSON.stringify(data),
headers: {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json'
}
});

PHP


$client = new GuzzleHttp\Client();
$data = [
  "title" => "Your video title", // trimmed, max 100 characters
  "visibility" => "private" | "public", // optional
  "description" => "Optional description",
  "categories" => ["category-id", "..."], // optional
  "tags" => ["tag-id", "..."], // optional
  "customMetadata" => ["externalId" => "celum-123"], // optional
  "duration" => 90, // optional, seconds
  "fps" => 25, // optional
  "orientation" => "landscape" // optional: "landscape" | "portrait"
];
 
$response = $client->request('PUT', 'https://app.ignitevideo.cloud/api/videos/upload', [
'body' => json_encode($data),
'headers' => [
  'Authorization' => 'Bearer YOUR_TOKEN',
  'Content-Type' => 'application/json'
]
]);

Se tens um vídeo com conteúdo falado e queres que a autotranscrição por IA comece logo após a codificação do vídeo, podes fazê-lo definindo dois parâmetros adicionais no pedido PUT para criares o novo vídeo:


{ 
  ...,
  "language": string, // "de-DE" | "..."  locale of the spoken language
  "autoTranscribe": true
}

Resposta

signedUrl expira ao fim de 1 hora. Para um carregamento multipart, define useMultipart como true. A resposta passa então a conter multipartUpload em vez de signedUrl. Consulta Multipart upload.


{
  "videoId": "[VIDEO_ID]",
  "title": "Your video title",
  "signedUrl": "[SIGNED_URL]"
}

Carregar ficheiro de vídeo

Carrega o teu ficheiro de vídeo com um pedido PUT para o URL assinado devolvido no passo anterior. Tens de passar o tipo MIME do ficheiro no cabeçalho Content-Type. Podes obter o tipo MIME a partir do teu ficheiro de vídeo local através do elemento de input de ficheiro.

Para ficheiros grandes (mais de 100 MB), recomendamos usar multipart upload, que oferece maior fiabilidade e suporta ficheiros até 60 GB. Também podes usar a biblioteca Uppy para uma implementação mais simples com fragmentação automática e acompanhamento do progresso.

CURL


curl -X PUT [SIGNED_URL] \
  -H "Content-Type: [MIME_TYPE]" \
  --data-binary "@[PATH_TO_VIDEO_FILE]"

JavaScript / Node.js


const response = await fetch([SIGNED_URL], {
  method: 'PUT',
  body: [VIDEO_FILE],
  headers: {
    'Content-Type': [MIME_TYPE]
  }
});

PHP


$client = new GuzzleHttp\Client();
$response = $client->request('PUT', [SIGNED_URL], [
  'body' => [VIDEO_FILE],
  'headers' => [
    'Content-Type' => [MIME_TYPE]
  ]
]);

Processo de codificação

Depois de o ficheiro de vídeo ter sido carregado, inicia-se a codificação. Este processo pode demorar algum tempo, consoante o tamanho do vídeo e a complexidade da codificação.

Consulta o estado da codificação com GET /api/videos/[VIDEO_ID], conforme descrito em obter vídeo. Um intervalo de polling de alguns segundos costuma ser suficiente. Enquanto a codificação decorre, status é PROGRESSING e statusProgress é uma percentagem de 0 a 100.

Exemplo de campos durante a codificação:


{
  "id": "[VIDEO_ID]",
  "status": "PROGRESSING",
  "statusProgress": 36,
  "errorCode": null,
  "errorMessage": null
}

Quando a codificação tem sucesso, status passa a COMPLETE, statusProgress é 100, e as fontes de reprodução ficam disponíveis em src.

Quando a codificação falha, status passa a ERROR. Usa errorCode para tratamento programático e errorMessage como alternativa legível. Consulta Estado de codificação para o ciclo de vida completo, os valores de estado e os códigos de erro.

Também podes subscrever webhooks video.updated em vez de fazer polling. As atualizações de progresso podem disparar-se com frequência durante a codificação. Consulta Webhooks.