Puntos finales de carga de vídeo, autenticación y flujo de solicitudes
Esta página documenta la práctica API de carga: cómo crear una clave, qué cabecera enviar, qué endpoint llamar para cada estrategia de carga y qué restricciones importan en producción.
Inicio rápido
Si sólo necesita el camino más corto hacia una integración que funcione, siga primero estos tres pasos y utilice después la referencia del punto final.
Crear una clave API en el panel de control
Las claves API se generan a través de una sesión de salpicadero autenticada por el portador. La clave devuelta solo se muestra una vez, así que guárdela inmediatamente.
Enviar X-Api-Key en solicitudes de carga
Los puntos finales de creación, finalización, cancelación y estado de carga aceptan la clave de API sin procesar en el encabezado X-Api-Key. No añada Bearer como prefijo.
Elija el flujo de carga que mejor se adapte a su infraestructura
Utilice multipart/form-data para la integración más corta, presign-put para la carga directa de objetos, o multipart presigning para archivos más grandes y transferencia reanudable.
Modelo de autenticación
La gestión de claves está protegida por la autenticación del portador, mientras que la ejecución de la carga acepta la autenticación del portador o la clave API sin procesar. La cabecera específica de carga es X-Api-Key y debe contener la cadena de clave completa sin prefijo.
Nota operativa: Las solicitudes de carga sólo funcionan cuando las cuentas de destino ya están vinculadas al inquilino actual. Las claves API no sustituyen el paso de vinculación de cuentas en el panel de control.
curl -X POST "$BASE_URL/api-keys/generate" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{
"name": "CI uploads"
}'curl -X GET "$BASE_URL/api/upload/$UPLOAD_ID/status" \
-H "X-Api-Key: $API_KEY"Referencia del punto final
Estas son las rutas que importan para la automatización de carga de extremo a extremo. La tabla se centra en el modo de autenticación, el tipo de carga útil y la tarea que realiza cada punto final.
/api-keys/generate Generar clave API
Crea una nueva clave para el inquilino actual. El cuerpo de la solicitud admite un campo de nombre opcional. La clave completa solo se devuelve en esta respuesta.
- Aut
- Portador JWT
- Solicitar
- application/json
/api/upload Carga directa de formularios
Carga los metadatos y el archivo binario en una sola solicitud. Ideal para clientes sencillos e integraciones de servidor más pequeñas.
- Aut
- X-Api-Key o portador JWT
- Solicitar
- multipart/form-data
/api/upload/presign-put Crear sesión de carga de una sola entrada
Devuelve un token de sesión, un id de archivo y una URL de subida directa. Después de subir el objeto, finaliza el flujo con /api/upload/complete.
- Aut
- X-Api-Key o portador JWT
- Solicitar
- application/json
/api/upload/multipart Crear sesión de carga multiparte
Devuelve URLs preasignadas para cada parte junto con el token de sesión. Úsalo cuando archivos grandes o redes inestables hagan más segura la transferencia por trozos.
- Aut
- X-Api-Key o portador JWT
- Solicitar
- application/json
/api/upload/complete Sesión de carga completa
Finaliza el flujo de entrada única o multiparte y crea el registro de carga real que inicia el procesamiento contra las cuentas de destino.
- Aut
- X-Api-Key o portador JWT
- Solicitar
- application/json
/api/upload/abort Abortar sesión de carga
Cancela una sesión de carga inacabada y elimina el objeto escenificado cuando es posible.
- Aut
- X-Api-Key o portador JWT
- Solicitar
- application/json
/api/upload/{uploadId}/status Obtener el estado de la carga
Devuelve el estado agregado más los detalles de entrega por cuenta, incluidos los identificadores externos y la información sobre fallos cuando está disponible.
- Aut
- X-Api-Key o portador JWT
- Solicitar
- Ningún cuerpo
/uploads Lista de cargas de inquilinos
Punto final centrado en el panel de control para el historial de cargas paginado. No se expone mediante autenticación de clave de API.
- Aut
- Sólo portador JWT
- Solicitar
- Parámetros de consulta
Reglas de validación y límites para modelar en su cliente
- Los archivos deben tener un tamaño superior a 0 bytes y no superar los 2 GB.
- Cada subida necesita al menos una cuenta vinculada que pertenezca al inquilino actual.
- El campo del título es obligatorio y tiene un límite de 2200 caracteres.
- Los puestos programados no pueden colocarse con más de un año de antelación.
- La cuota se cobra por cuenta de destino, no por solicitud de API.
- Al incluir metadatos de YouTube, categoryId, defaultLanguage y defaultAudioLanguage pasan a ser obligatorios.
Significado del estatus público
Scheduled
El registro de carga está aceptado y a la espera de su ventana de envío programada.
Processing
La carga se está enviando o reintentando activamente. Los estados internos de reintento y envío se presentan como Procesando.
Uploaded
La plataforma de destino ha confirmado la publicación de la anotación en cuenta.
Failed
No se ha podido completar la carga de al menos un destino. Compruebe los valores de errorCode y errorMessage por cuenta.
Solicitar ejemplos
Utilice estos ejemplos como puntos de partida. Sustituya los marcadores de posición por su URL base, token de portador, clave API, identificadores de cuenta y rutas de archivo reales.
curl -X POST "$BASE_URL/api/upload" \
-H "X-Api-Key: $API_KEY" \
-F "title=Spring launch teaser" \
-F "accounts=account_123" \
-F "accounts=account_456" \
-F "scheduledOn=2026-04-18T09:30:00Z" \
-F "file=@./video.mp4"curl -X POST "$BASE_URL/api/upload/presign-put" \
-H "X-Api-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Spring launch teaser",
"accounts": ["account_123"],
"fileName": "video.mp4",
"fileSize": 734003200,
"contentType": "video/mp4"
}'
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
--data-binary @./video.mp4
curl -X POST "$BASE_URL/api/upload/complete" \
-H "X-Api-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionToken": "$SESSION_TOKEN",
"parts": []
}'¿Quiere también una visión general de la arquitectura?
El primer artículo del blog de Upload24 explica por qué la API se divide en gestión de claves, creación de sesiones de carga y seguimiento de entrega por cuenta.