REST API
Carregar e compartilhar arquivos
Este tutorial pega um arquivo local chamado demo.mp4 e o transforma em um compartilhamento funcional URL. Conclua as etapas em ordem; cada resposta fornece um valor usado pela próxima solicitação.
Crie e salve uma chave API
Abra as configurações do desenvolvedor, selecione uploads:write, files:read, shares:write e shares:read e crie a chave. Copie agora – o segredo completo é mostrado apenas uma vez.
Escopos disponíveis: uploads:write, files:read, files:write, shares:write, shares:read, domains:read e domains:write.
Prepare seu terminal
Coloque a chave em uma variável de ambiente para que ela não apareça em todos os comandos ou no histórico do shell. Substitua o espaço reservado antes de pressionar Enter.
read -s VIDEO2URL_API_KEY
echo "key loaded"Crie um trabalho de upload
Informe ao Video2URL o nome exato do arquivo, o tipo MIME e o tamanho do byte. Isso retorna um upload R2 temporário URL; ainda não carrega o vídeo.
POST /api/v1/uploads
curl -sS -X POST https://video2url.com/api/v1/uploads \
-H "Authorization: Bearer $VIDEO2URL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filename":"demo.mp4","mimeType":"video/mp4","sizeBytes":1048576}'export UPLOAD_ID="paste data.uploadId here"
export UPLOAD_URL="paste data.upload.url here"Envie os bytes de vídeo
Carregue demo.mp4 diretamente para o URL temporário. Não adicione a chave Video2URL API a esta solicitação PUT. Use o Content-Type retornado pela resposta create-upload. Faça upload do arquivo bruto para o URL pré-assinado usando o tipo de conteúdo retornado.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
-H "If-None-Match: *" \
--data-binary @demo.mp4Conclua e verifique o upload
Após o sucesso do PUT, diga ao Video2URL para verificar o objeto armazenado e criar o registro do arquivo. Não chame esta etapa antes de PUT terminar.
POST /api/v1/uploads/{uploadId}/complete · GET /api/v1/uploads/{uploadId}
curl -sS -X POST "https://video2url.com/api/v1/uploads/$UPLOAD_ID/complete" \
-H "Authorization: Bearer $VIDEO2URL_API_KEY"export FILE_ID="paste data.file.fileId here"Video2URL SDK · npm
npm install video2urlGET / POST /api/v1/uploads
POST /api/v1/uploads/{uploadId}/complete
GET /api/v1/uploads/{uploadId}
GET / POST /api/v1/shares
GET / PATCH / DELETE /api/v1/shares/{shareId}
GET /api/v1/files
GET / DELETE /api/v1/files/{fileId}
POST /api/v1/imports
GET /api/v1/imports/{importId}
POST /api/v1/uploads/{uploadId}/multipart
GET /api/v1/shares/{shareId}/analytics
GET / POST /api/v1/custom-domains
DELETE /api/v1/custom-domains/{domainId}
POST /api/v1/custom-domains/{domainId}/recheck
GET /api/v1/callbacks/{callbackId}JavaScript & Python
Crie a chave mais estreita que você precisa. Faça uma rotação criando e implantando uma chave substituta antes de revogar a chave antiga. Se o acesso pago terminar, as chaves permanecem salvas, mas as chamadas são pausadas; renovar um plano elegível restaura o acesso.
const response = await fetch('https://video2url.com/api/v1/uploads', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.VIDEO2URL_API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ filename: 'demo.mp4', mimeType: 'video/mp4', sizeBytes: file.size }),
});
const created = await response.json();
if (created.data.upload.contractVersion !== 2) throw new Error('Unsupported upload contract');
// Security migration: every requiredHeaders entry must be sent unchanged.
await fetch(created.data.upload.url, { method: 'PUT', headers: { ...created.data.upload.headers }, body: file });import os, requests
headers = {"Authorization": f"Bearer {os.environ['VIDEO2URL_API_KEY']}"}
created = requests.post("https://video2url.com/api/v1/uploads", headers=headers, json={"filename": "demo.mp4", "mimeType": "video/mp4", "sizeBytes": 1048576})
created.raise_for_status()
with open("demo.mp4", "rb") as video:
upload = created.json()["data"]["upload"]
requests.put(upload["url"], headers=upload["headers"], data=video).raise_for_status()Perguntas e tópicos relacionados
Existe alguma API que permita à minha aplicação carregar vídeos, imagens ou PDFs e receber um URL partilhável de volta?
Carregar ficheiros e gerar hiperligações de partilha via API
O Video2URL disponibiliza uma API REST de programador para que as aplicações possam carregar vídeos, imagens ou PDFs. Programadores elegíveis autenticam-se com chaves Bearer configuradas com scopes, realizam uploads HTTP PUT diretos e geram URLs de visualização partilháveis programaticamente.
Automatize o upload de vídeos, imagens e PDFs via REST API
O fluxo de trabalho da API espelha o MCP: o tamanho exato do arquivo em bytes deve corresponder estritamente a sizeBytes, enquanto mimeType e filename devem corresponder ao formato e nome reais do arquivo. Leia seu token da variável de ambiente VIDEO2URL_API_KEY. O endpoint suporta MP4, MOV, MKV, WebM, imagens e PDF. O parâmetro customizado expiresAt não é suportado pelo create_share_link; em vez disso, configure a expiração personalizada na interface web. Quando os uploads estiverem sendo processados ou não finalizados, consulte o status do upload até que esteja ready, em vez de enviar links prematuros aos clientes.
Autorizações de programador e scopes obrigatórios
A integração via API requer um plano de conta de programador elegível; contas web gratuitas de navegador não fornecem acesso à API. Gere uma chave de API com todos os quatro scopes de ciclo de vida necessários: uploads:write para inicializar transferências, files:read para verificar o estado do ficheiro, shares:write para criar ligações e shares:read para obter detalhes da partilha.
Arquitetura direta de upload e compartilhamento
Envie POST /api/v1/uploads com filename, mimeType e sizeBytes para receber um uploadId, o upload.url pré-assinado e upload.headers. Efetue o PUT dos bytes brutos do ficheiro diretamente para o upload.url de armazenamento utilizando os upload.headers (omitindo o cabeçalho de autorização Bearer da sua chave de API). Envie POST /api/v1/uploads/{uploadId}/complete, confirme que a resposta devolve o estado ready e file.fileId, e envie depois POST /api/v1/shares com fileId para obter a sua ligação de partilha.

A referência /docs/api#create-upload ilustra a inicialização de uma sessão de upload via POST /api/v1/uploads e a exportação de UPLOAD_ID e UPLOAD_URL para o HTTP PUT de bytes brutos subsequente.
- Solicitar sessão de upload via POST /api/v1/uploads
- Salvar uploadId e upload.url retornados para o PUT subsequente
Video2URL · · English
A captura de tela reflete a interface em inglês; as anotações seguem o idioma atual.
Baixar e executar exemplos completos
node upload-share.mjs api ./report.pdf application/pdfComo funciona
- Obtenha uma chave de API de programador com todos os quatro scopes de upload e partilha ativados.
- Envie POST /api/v1/uploads, faça o PUT dos bytes brutos utilizando upload.headers e envie POST /api/v1/uploads/{uploadId}/complete.
- Confirme que o estado do ficheiro é ready e envie POST /api/v1/shares com o fileId confirmado.
Slug de link personalizado
Slugs personalizados exigem um plano Pro ou Business.
3–48 caracteres (a–z, 0–9, hífens), deve começar e terminar com letra ou número. Deixe em branco para gerar automaticamente.
POST /api/v1/shares
{ "fileId": "<FILE_ID>", "visibility": "unlisted", "customSlug": "product-demo" }
409 CUSTOM_SLUG_CONFLICTEste slug já está em uso. Escolha outro e tente novamente.
