VberAI ofrece una API REST HTTP para integrar sus capacidades de IA (hoy AI Super Matting) en tus apps, juegos y pipelines. Autenticación con clave API y firma, códigos de error estandarizados, facturación por crédito.
API v1
Estable
Documentación API
Genera imágenes, elimina fondos y ejecuta las canalizaciones de IA de VberAI directamente sobre HTTP, con claves de API personales o de empresa.
La API de VberAI expone las mismas canalizaciones de IA que impulsan el studio —eliminación de fondo, recorte avanzado, generación de imágenes y más— como sencillos endpoints HTTP. Autentícate con una clave de API, envía un trabajo y lee el resultado o recíbelo mediante un webhook.
Una única forma de solicitud
Cada servicio recibe un cuerpo { input } y devuelve una tarea que puedes sondear o recibir por webhook.
Dos tipos de clave
Claves personales para desarrolladores individuales; claves de empresa para el uso servidor a servidor de una organización.
Facturación predecible
Los créditos se reservan al enviar y se liquidan al completarse con éxito; los trabajos fallidos se reembolsan automáticamente.
Cómo funciona
1Autentícate con tu clave de API en la cabecera X-API-Key.
2Envía un trabajo a un servicio con un cuerpo JSON { input }.
3Lee el resultado en línea (servicios síncronos) o sondea la tarea / recibe un webhook (servicios asíncronos).
bash
# 1. Submit a jobcurl-X POST https://api.vberai.com/api/ai/services/ai-image-bg-remove/execute \
-H"X-API-Key: vber_sk_YOUR_KEY" \
-H"Content-Type: application/json" \
-d'{"input": {"imageUrl": "https://example.com/photo.png"}}'# => { "data": { "taskId": "...", "status": "queued" } }# 2. Poll until status is "completed"curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H"X-API-Key: vber_sk_YOUR_KEY"
Autenticación y claves de API
Cada solicitud se autentica con una clave de API enviada en la cabecera X-API-Key. Hay dos tipos de clave y usan rutas distintas; elegir la ruta equivocada para tu tipo de clave es la causa más común de un 401.
Trata las claves de API como contraseñas. Envíalas solo desde tu backend, rótalas si se filtran y acota las claves de empresa con un límite de gasto.
Claves personales — vber_sk_
Para desarrolladores individuales. Se crean de forma autoservicio desde la página de claves de API de tu cuenta (requiere un plan con acceso a la API). Se cargan a tus créditos personales. Usa las rutas /ai/services y /ai/tasks.
Claves de empresa — vber_org_sk_
Para uso servidor a servidor por parte de una organización. Las emite un administrador de la organización en el portal de empresa y se limitan a los servicios para los que tu organización está aprobada. Se cargan al fondo de créditos de tu organización. Usa las rutas /ai/org-services.
Aspecto
Clave personal
Clave de empresa
Prefijo de la clave
vber_sk_
vber_org_sk_
Prefijo de la ruta
/ai/services, /ai/tasks
/ai/org-services
Cómo obtenerla
Autoservicio, ajustes de la cuenta
Administrador de la organización, portal de empresa
Se carga a
Créditos personales
Créditos de la organización
Límites
Límites de solicitudes por minuto / por día
Concurrencia por organización (personalizada)
http
X-API-Key: vber_sk_... # personal key
X-API-Key: vber_org_sk_... # enterprise key
URL base
text
https://api.vberai.com/api
Solicitudes y modos de ejecución
Cada servicio recibe un cuerpo JSON con un objeto input que contiene los parámetros del servicio. Cómo obtienes el resultado depende del modo de ejecución del servicio.
Servicios síncronos
Los servicios rápidos (por ejemplo, chat o traducción de texto) devuelven su resultado en línea en la misma respuesta con HTTP 200. No hace falta sondear.
Servicios asíncronos
Los servicios más pesados (generación de imágenes, recorte, eliminación de fondo) devuelven HTTP 202 con un taskId. Sondea la tarea o recibe el resultado en un webhook cuando termine.
Clave personal
Las claves personales usan un único endpoint por servicio: POST /ai/services/{code}/execute. Devuelve el resultado en línea (200) para los servicios síncronos, o una tarea (202) para los asíncronos; el mismo endpoint en ambos casos.
Clave de empresa
Las claves de empresa usan dos endpoints: /execute para los servicios síncronos y /execute-async para los asíncronos. Llamar al equivocado devuelve 400 indicándote qué endpoint usar.
Los trabajos asíncronos devuelven un taskId. Sondea la tarea hasta que su status sea un valor terminal y, después, lee el resultado. La ruta que sondeas depende de tu tipo de clave; esto es lo más importante que debes acertar.
Qué ruta sondear
Acción
Clave personal
Clave de empresa
Sondear el estado de la tarea
GET /ai/tasks/{taskId}
GET /ai/org-services/tasks/{taskId}
Volver a firmar URLs de descarga nuevas
Se lee de la respuesta de estado
GET /ai/org-services/tasks/{taskId}/outputs
Cancelar una tarea
POST /ai/tasks/{taskId}/cancel
No disponible
Estado por lotes
GET /ai/tasks/batch-status
No disponible
Las claves de empresa deben sondear la ruta /ai/org-services
Una clave de empresa (vber_org_sk_) enviada a una ruta personal /ai/tasks devuelve 401 INVALID_API_KEY: las rutas personales solo aceptan claves personales. Sondea siempre los trabajos de empresa en /ai/org-services/tasks/{taskId}. cancel y batch-status son exclusivos de las claves personales.
Estados de la tarea
Una tarea pasa por estos valores. Deja de sondear en cuanto alcances un status terminal: completed, failed, cancelled o timeout.
Cuando status es completed, result.assets contiene las imágenes de salida. Cada asset tiene una url (un enlace de descarga prefirmado que caduca), un mimeType y un index; width, height, size y expiresAt aparecen cuando están disponibles. Obtén las URLs sin demora: las claves de empresa pueden volver a solicitar enlaces nuevos desde el endpoint /outputs.
La idempotencia te permite reintentar de forma segura un envío tras un error de red sin crear un trabajo duplicado ni que se te cobre dos veces.
Claves de empresa
Envía una cabecera opcional Idempotency-Key (un valor que generas tú, de hasta 200 caracteres; un UUID es lo ideal) en /execute-async. Reintentar con la misma clave devuelve la tarea original en lugar de crear una nueva. El servidor solo deduplica; no genera la clave por ti.
Claves personales
Las solicitudes con clave de API personal no admiten actualmente una clave de idempotencia. Reintenta solo tras confirmar que la solicitud anterior no creó una tarea (sondea con el taskId que recibiste).
En lugar de sondear, puedes hacer que VberAI envíe el resultado mediante POST a tu servidor cuando una tarea alcanza un estado terminal.
Configurar un webhook
Pasa un webhookUrl HTTPS público (y un webhookSecret opcional) al enviar el trabajo. Las claves de empresa los leen del nivel superior del cuerpo; las claves personales los leen de options.
Verificar la firma
Si defines un webhookSecret, cada entrega incluye una cabecera X-Webhook-Signature: un HMAC-SHA256 de la carga JSON en bruto, codificado en hexadecimal. Vuelve a calcularlo con tu secreto y compáralo antes de confiar en la carga. Las entregas también llevan un X-Idempotency-Key (taskId + status) para que puedas ignorar los duplicados.
Las entregas fallidas se reintentan varias veces con retroceso exponencial. Responde con 2xx para confirmar la recepción.
Los trabajos de IA cuestan créditos. Se aplica el mismo precio a las claves personales y de empresa; solo cambia la cartera: las claves personales consumen tus créditos personales y las de empresa, el fondo de tu organización.
Reservar, liquidar, reembolsar
Los créditos se reservan cuando se acepta un trabajo y se liquidan por el importe exacto cuando este se completa. Si un trabajo falla o se cancela, la reserva se reembolsa por completo: nunca se te cobra por un trabajo fallido.
Cómo se calcula el coste
El coste depende del servicio. Algunos servicios cobran un importe fijo por solicitud; otros escalan con la resolución de salida (por píxel) o según el borde más largo. Llama al endpoint cost para previsualizar el cargo exacto antes de ejecutar un trabajo.
•Por solicitud: un importe fijo en cada llamada.
•Por píxel: escala con width × height de la salida.
•Por dimensión: se cobra según el borde más largo de la salida.
La limitación de tasa varía según el tipo de clave. Ambas se configuran por servicio en el backend; los valores de abajo describen el mecanismo, no cifras fijas.
Claves personales — tasa de solicitudes
Las claves personales están limitadas por solicitudes por minuto y por día, configuradas por servicio. Cada respuesta lleva las cabeceras de abajo para que puedas regular el ritmo de tus llamadas.
Cabecera
Descripción
X-RateLimit-Limit-Minute
Solicitudes permitidas por minuto.
X-RateLimit-Remaining-Minute
Solicitudes restantes en la ventana del minuto actual.
X-RateLimit-Limit-Day
Solicitudes permitidas por día.
X-RateLimit-Remaining-Day
Solicitudes restantes en la ventana del día actual.
No hay cabecera X-RateLimit-Reset. En un 429, el cuerpo de la respuesta incluye retryAfter y resetIn.
Claves de empresa — concurrencia
Las claves de empresa no se limitan por tasa de solicitudes, sino por cuántos trabajos pueden ejecutarse de forma concurrente para tu organización. El límite es personalizado por organización (y puede ser ilimitado); superarlo devuelve 429 CONCURRENCY_LIMIT_EXCEEDED. Las respuestas de empresa no llevan cabeceras X-RateLimit.
Cada respuesta incluye success, message y timestamp. En caso de fallo, un código de error identifica el problema. Ramifica según el código, no según el texto del message: los mensajes pueden cambiar y están solo en inglés.
Dónde reside el código
Los errores de empresa son coherentes: los problemas de autenticación ponen el código en data.code, mientras que los de servicio y facturación lo ponen en el errorCode de nivel superior. Los errores personales varían según el endpoint (errorCode de nivel superior, data.code o errors.code); lee el campo indicado para cada código.
Códigos de estado HTTP
Estado
Significado
200
Éxito: el resultado se devuelve en línea.
202
Aceptado: se creó una tarea asíncrona; sondea o espera el webhook.
400
Solicitud incorrecta: entrada no válida o endpoint equivocado para el modo de ejecución del servicio.
401
No autorizado: clave de API ausente, mal formada o de tipo incorrecto.
402
Pago requerido: créditos insuficientes.
403
Prohibido: la clave o la cuenta no puede usar este servicio.
404
No encontrado: tarea desconocida o una tarea que no es tuya.
429
Demasiadas solicitudes: se superó el límite de tasa o de concurrencia.
500
Error del servidor: vuelve a intentarlo; el trabajo (si lo hay) se reembolsa.
Códigos de error comunes
Código
Ubicación
Significado
INSUFFICIENT_CREDITS
errorCode
Créditos personales insuficientes para el trabajo.
INSUFFICIENT_ORG_CREDITS
errorCode
Créditos de la organización insuficientes para el trabajo.
ORG_API_KEY_REQUIRED
data.code
Este endpoint necesita una clave de API de empresa (X-API-Key).
INVALID_ORG_API_KEY
data.code
La clave de empresa está ausente, mal formada o revocada.
INVALID_API_KEY
data.code
El formato de la clave de API no es válido: a menudo, una ruta personal llamada con una clave de empresa (o viceversa).
API_SERVICE_NOT_ALLOWED
errorCode
Tu organización no está aprobada para este servicio.
ORG_DISABLED
data.code
La cuenta de la organización está deshabilitada.
CONCURRENCY_LIMIT_EXCEEDED
errorCode
Demasiados trabajos concurrentes para tu organización.
SERVICE_NOT_EXTERNALLY_ACCESSIBLE
errorCode
Este servicio no está disponible a través de la API externa.
Detalles concretos de solicitud y respuesta por servicio. Los ejemplos muestran ambos tipos de clave; elige la pestaña de la clave que tengas. Para los conceptos en los que se apoyan (sondeo, estados, errores, facturación), consulta las guías anteriores.
Los dos servicios siguientes están documentados por completo. Para la lista completa y en vivo de servicios que tu clave puede llamar —y la especificación de parámetros de cada servicio—, consulta los endpoints del catálogo. Esta es la fuente autorizada, ya que la disponibilidad depende de tu plan y de las aprobaciones de la organización.
Endpoint
Descripción
GET /ai/services
Lista los servicios a los que tu clave puede acceder.
GET /ai/external/services/{code}/spec
Obtén la especificación de parámetros de un servicio.