Saltar al contenido principal
POST
Iniciar una subida directa de Blob
Inicia una subida directa: los bytes van desde tu cliente directamente al almacenamiento, no a través de la API. Los archivos de hasta el límite de una sola parte de tu plan se devuelven en modo single, con una url. Los archivos más grandes se devuelven en modo multipart, con un tamaño de parte y un número de partes. Después envía los bytes y llama a Completar una subida directa. El almacenamiento reservado cuenta para la cuota hasta que la subida se complete, se cancele o caduque. Ámbito: blob:write. Acepta un token de subida. Token de subida: esta ruta también acepta un token de subida (Authorization: Bearer vcup_...) en lugar de una clave de API.
string
requerido
Ruta de destino, con las mismas reglas que Subir en una sola petición.
number
requerido
Tamaño exacto del archivo en bytes, de 0 a 10 GB. Los bytes almacenados deben coincidir con él.
string
public o private. Por defecto, private.
boolean
Reemplaza un objeto que ya existe en path. Por defecto, false.
boolean
Cuando path está ocupada, guarda el archivo como nombre-1.ext, nombre-2.ext y así sucesivamente (el primer nombre libre) en lugar de devolver BLOB_OBJECT_ALREADY_EXISTS. La subida lleva el path final. Por defecto, false. No se puede combinar con overwrite y no tiene efecto con un token de subida que fija el path.
boolean
Inserta un sufijo aleatorio antes de la extensión. Por defecto, false; se fuerza a true con un token de subida sin path fijo.
string
immutable, max-age=<seconds> o no-cache (Enterprise-26 o superior).
string
inline o attachment. HTML, SVG, XML, XHTML y HTM siempre son attachment.
string
Nombre sugerido al descargar.
string
Marca de tiempo ISO 8601 para la eliminación, como mínimo el mínimo del plan a partir de ahora.
string
SHA-256 en hexadecimal de todo el archivo. Se comprueba al completar la subida. Solo es válido para una subida directa enviada en una sola parte; una subida multiparte lo rechaza con VALIDATION_ERROR.
object
Hasta 5 claves, cada una [a-z0-9-]{1,64}, 512 bytes en total. Enterprise-12 o superior.
string
El ID del workspace, cuando el blob pertenece a un workspace. La llamada actúa sobre el blob del propietario del workspace y necesita el permiso de workspace blob:read (blob:manage en las rutas que modifican datos). Omítelo para actuar sobre tu propio blob.

Ejemplo de petición

Respuesta

object
La subida, con las URL a las que enviar los bytes.

Respuestas de error

string
El código de error que indica el motivo del fallo. Valores posibles:
  • AUTH_TOKEN_MISSING (401): No se envió la cabecera Authorization.
  • API_KEY_INVALID (401): La clave de API no existe, fue revocada o su secreto no coincide.
  • API_KEY_SCOPE_DENIED (403): La clave no tiene el ámbito que necesita esta ruta (blob:read o blob:write); details.required lo indica.
  • WORKSPACE_PERMISSION_DENIED (403): Solo con workspace_id: no eres miembro o tu rol no tiene el permiso de blob.
  • WORKSPACE_NOT_FOUND (404): Solo con workspace_id: no existe ningún workspace con ese ID o no eres miembro.
  • BLOB_UPLOAD_TOKEN_INVALID (401): El token de subida no existe, ha caducado o fue revocado (solo con un token de subida).
  • BLOB_NAMESPACE_SUSPENDED (403): El almacenamiento blob de la cuenta está suspendido o su plan ha caducado. Las subidas y demás escrituras se rechazan desde el inicio del periodo de gracia de 72 horas.
  • VALIDATION_ERROR (400): Un parámetro o campo del cuerpo no superó la validación. details.path indica el campo.
  • BLOB_UPLOAD_TOKEN_CONSTRAINT (403): Solo con un token de subida: la ruta, la carpeta u otra opción que fija el token no coincide con la petición.
  • PLAN_RESTRICTED_FEATURE (403): No está incluido en el plan metadata (por debajo de Enterprise-12) ni cache_control: no-cache (por debajo de Enterprise-26).
  • BLOB_UPLOAD_LIMIT (409): La cuenta ya tiene tantas subidas en curso como permite su plan (max_open_uploads).
  • BLOB_OBJECT_ALREADY_EXISTS (409): path está ocupada y overwrite no es true.
  • BLOB_FILE_TOO_LARGE (413): size supera los 10 GB, el max_size de la regla de la carpeta o el max_size del token.
  • STORAGE_QUOTA_EXCEEDED (403): El tamaño reservado más lo ya usado superaría la cuota de blob del plan.
  • BLOCKED_FILE_TYPE (422): La extensión está bloqueada o no está permitida por la regla de la carpeta o por el token.
  • BLOB_UPLOAD_TOKEN_EXHAUSTED (401): Solo con un token de subida: ha agotado todos sus usos.
  • RATE_LIMIT_EXCEEDED (429): Por debajo de Enterprise-12, las subidas están limitadas a 1 por segundo. details.retry_after indica la espera.
Última modificación el 28 de octubre de 2026