Saltar al contenido principal
POST
Sube material de referencia y recibe directamente una URL pública al completarse, sin consultas periódicas. La subida es gratuita, pero el saldo de la cuenta debe ser positivo. Los tres endpoints comparten una cuota por usuario: 2000 archivos en 72 horas de forma predeterminada.
El Playground de la documentación no admite subidas de archivos. Usa los ejemplos cURL, Python o JavaScript. El ejemplo JavaScript requiere un <input type="file"> con un archivo seleccionado.

Autenticación

string
requerido
Usa una APIMart API Key válida, habilitada y no caducada como Bearer <token>. La cuenta no debe estar suspendida y debe tener saldo positivo. Agotar la cuota propia de la Key no impide subir archivos. Consigue una Key en Gestión de API Keys.

Parámetros de solicitud

file
requerido
Envía un archivo con su nombre en el campo file de una solicitud multipart/form-data. No sustituyas la parte de archivo por JSON, una cadena base64 o una URL. Otros campos se ignoran; si envías varias partes file, solo se procesa la primera.Formatos admitidos: MP4 (.mp4), MOV (.mov), WebM (.webm)Tamaño máximo predeterminado: 50MB. Los límites son configurables. Se aplica la configuración activa y el límite indicado en el mensaje de error.
Con cURL --form, Python files o JavaScript FormData, deja que el cliente genere Content-Type con su boundary. No establezcas esa cabecera manualmente.

Validación de archivos

El tipo se identifica por el contenido, no por la extensión ni el MIME declarado. El contenido debe coincidir con el endpoint. Cambiar el nombre no convierte el formato; un tipo incorrecto devuelve HTTP 400. Se valida la estructura del contenedor. Se rechazan cabeceras falsas y contenedores dañados. Solo se admiten los formatos siguientes; renombrar AVI, MKV u otros no los hace compatibles.

Respuesta correcta

HTTP 200 devuelve los datos del archivo. url está en la raíz JSON, sin envoltorio data ni ID de tarea de generación.
string
URL pública para el parámetro de referencia correspondiente de la API de generación. Cada modelo conserva sus límites de formato, tamaño, cantidad y duración. Una subida correcta no garantiza compatibilidad con el modelo.
string
Nombre original del archivo.
string
Tipo MIME detectado por el servidor a partir del contenido, no el valor declarado por el cliente.
string
Categoría del archivo. Este endpoint devuelve video.
integer
Tamaño real en bytes.
integer
Fecha de subida como marca de tiempo Unix en segundos.
object
Información opcional de cuota. Los campos de usuarios con límite se enumeran abajo. La estructura puede variar si el acceso es ilimitado o las estadísticas no están disponibles.

Cuota compartida y límites de solicitudes

Imágenes, vídeos y audios comparten una cuota por usuario. Varias Keys del mismo usuario no suman cuota. La ventana avanza a cada hora en punto y cuenta por defecto las subidas correctas de las últimas 71–72 horas aproximadamente. Los archivos inválidos, demasiado grandes o no guardados no consumen cuota de archivos. Las respuestas limitadas normales incluyen X-Upload-Quota-Limit, X-Upload-Quota-Remaining y X-Upload-Quota-Reset, correspondientes a limit, remaining y reset_at. Reset usa segundos Unix. Los usuarios sin límite reciben quota: {"unlimited": true} sin esas tres cabeceras. Si las estadísticas no están disponibles, una respuesta correcta puede omitir quota. No interpretes esa ausencia como cero o ilimitado, ni vuelvas a subir el archivo solo por ello. Al agotar la cuota de archivos se devuelve HTTP 429, error.type: rate_limit_exceeded, quota con remaining: 0 y Retry-After. Espera los segundos indicados. Existe otro límite independiente de 1000 solicitudes por Key cada 60 segundos, identificado por rate_limit_error.

Gestión de errores

Los errores aparecen en el objeto error de la raíz JSON. Consulta el estado HTTP, error.type / error.code y error.message.

Uso de URL y conservación

72 horas es la ventana de cuota predeterminada, no una garantía de conservación. La duración depende de la política de almacenamiento. Conserva los originales y usa las URL pronto para generar; no asumas que son permanentes.

Otros endpoints de subida