Pular para o conteúdo principal
POST
Iniciar um upload direto para o Blob
Inicia um upload direto: os bytes saem do seu cliente direto para o armazenamento, sem passar pela API. Arquivos até o limite de parte única do plano voltam no modo single, com uma url. Arquivos maiores voltam no modo multipart, com tamanho e quantidade de partes. Depois envie os bytes e chame Concluir um upload direto. O armazenamento reservado conta na cota até o upload ser concluído, abortado ou expirar. Escopo: blob:write. Aceita um token de upload. Token de upload: esta rota também aceita um token de upload (Authorization: Bearer vcup_...) em vez de uma chave de API.
string
obrigatório
Caminho de destino, com as mesmas regras de Upload em uma única requisição.
number
obrigatório
Tamanho exato do arquivo em bytes, de 0 até 10 GB. Os bytes armazenados precisam bater com ele.
string
public ou private. Padrão private.
boolean
Substitui um objeto que já esteja em path. Padrão false.
boolean
Quando path já está ocupado, salva o arquivo como name-1.ext, name-2.ext e assim por diante (o primeiro nome livre), em vez de retornar BLOB_OBJECT_ALREADY_EXISTS. O upload carrega o path final. Padrão false. Não pode ser combinado com overwrite e não tem efeito com um token de upload que fixa o path.
boolean
Insere um sufixo aleatório antes da extensão. Padrão false; é forçado para true em um token de upload sem path fixo.
string
immutable, max-age=<segundos> ou no-cache (Enterprise-26 ou superior).
string
inline ou attachment. HTML, SVG, XML, XHTML e HTM são sempre attachment.
string
Nome sugerido no download.
string
Timestamp ISO 8601 para a exclusão, no mínimo o prazo mínimo do plano a partir de agora.
string
SHA-256 em hexadecimal do arquivo inteiro. Verificado quando o upload é concluído. Só vale para um upload direto enviado em uma única parte; um upload multipart recusa com VALIDATION_ERROR.
object
Até 5 chaves, cada uma [a-z0-9-]{1,64}, 512 bytes no total. Enterprise-12 ou superior.
string
O ID do workspace, quando o blob pertence a um workspace. A chamada atua sobre o blob do dono do workspace e precisa da permissão de workspace blob:read (blob:manage nas rotas que alteram dados). Omita para atuar sobre o seu próprio blob.

Exemplo de requisição

Resposta

object
O upload, com as URLs para enviar os bytes.

Respostas de erro

string
O código de erro que indica o motivo da falha. Valores possíveis:
  • AUTH_TOKEN_MISSING (401): Nenhum header Authorization foi enviado.
  • API_KEY_INVALID (401): A chave de API não existe, foi revogada ou o segredo não confere.
  • API_KEY_SCOPE_DENIED (403): A chave não tem o escopo que a rota exige (blob:read ou blob:write); details.required informa qual.
  • WORKSPACE_PERMISSION_DENIED (403): Somente com workspace_id: você não é membro, ou seu papel não tem a permissão de blob.
  • WORKSPACE_NOT_FOUND (404): Somente com workspace_id: não existe workspace com esse ID, ou você não é membro.
  • BLOB_UPLOAD_TOKEN_INVALID (401): O token de upload não existe, expirou ou foi revogado (somente com token de upload).
  • BLOB_NAMESPACE_SUSPENDED (403): O armazenamento de blob da conta está suspenso, ou o plano expirou. Uploads e outras gravações são recusados desde o início do período de carência de 72 horas.
  • VALIDATION_ERROR (400): Um parâmetro ou campo do body falhou na validação. details.path informa o campo.
  • BLOB_UPLOAD_TOKEN_CONSTRAINT (403): Somente com token de upload: o caminho, a pasta ou outra opção que o token fixa não confere com a requisição.
  • PLAN_RESTRICTED_FEATURE (403): metadata (abaixo do Enterprise-12) ou cache_control: no-cache (abaixo do Enterprise-26) não estão incluídos no plano.
  • BLOB_UPLOAD_LIMIT (409): A conta já tem tantos uploads em andamento quanto o plano permite (max_open_uploads).
  • BLOB_OBJECT_ALREADY_EXISTS (409): path já está ocupado e overwrite não é true.
  • BLOB_FILE_TOO_LARGE (413): size está acima de 10 GB, acima do max_size da regra da pasta, ou acima do max_size do token.
  • STORAGE_QUOTA_EXCEEDED (403): O tamanho reservado somado ao que já está em uso ultrapassaria a cota de blob do plano.
  • BLOCKED_FILE_TYPE (422): A extensão está bloqueada ou não é permitida pela regra da pasta ou pelo token.
  • BLOB_UPLOAD_TOKEN_EXHAUSTED (401): Somente com token de upload: ele já usou todos os seus usos.
  • RATE_LIMIT_EXCEEDED (429): Abaixo do Enterprise-12, os uploads são limitados a 1 por segundo. details.retry_after informa a espera.
Última modificação em 28 de outubro de 2026