API para desarrolladores de VberAI

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.

Introducción

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

  1. 1Autentícate con tu clave de API en la cabecera X-API-Key.
  2. 2Envía un trabajo a un servicio con un cuerpo JSON { input }.
  3. 3Lee el resultado en línea (servicios síncronos) o sondea la tarea / recibe un webhook (servicios asíncronos).
bash
# 1. Submit a job
curl -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.

AspectoClave personalClave de empresa
Prefijo de la clavevber_sk_vber_org_sk_
Prefijo de la ruta/ai/services, /ai/tasks/ai/org-services
Cómo obtenerlaAutoservicio, ajustes de la cuentaAdministrador de la organización, portal de empresa
Se carga aCréditos personalesCréditos de la organización
LímitesLímites de solicitudes por minuto / por díaConcurrencia 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.
json
{
  "input": {
    "imageUrl": "https://example.com/photo.png"
  },
  "webhookUrl": "https://your-server.com/hook"
}
bash
HTTP 200  # sync: result inline
HTTP 202  # async: { "taskId": "...", "status": "queued" }

Sondeo y resultados

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ónClave personalClave de empresa
Sondear el estado de la tareaGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Volver a firmar URLs de descarga nuevasSe lee de la respuesta de estadoGET /ai/org-services/tasks/{taskId}/outputs
Cancelar una tareaPOST /ai/tasks/{taskId}/cancelNo disponible
Estado por lotesGET /ai/tasks/batch-statusNo 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.

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

Lectura del resultado

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.

bash
# personal
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"

# enterprise
curl https://api.vberai.com/api/ai/org-services/tasks/{taskId} \
  -H "X-API-Key: vber_org_sk_YOUR_ORG_KEY"

Tarea completada

json
{
  "success": true,
  "data": {
    "taskId": "6a97e277a148c970dd545f40",
    "serviceCode": "super-matting",
    "status": "completed",
    "creditsEstimated": 10,
    "creditsActual": 10,
    "outputCount": 1,
    "result": {
      "type": "images",
      "assets": [
        {
          "index": 0,
          "url": "https://assets.vberai.org/tmp/user-assets/.../0.png?signature=...",
          "mimeType": "image/png",
          "expiresAt": "2026-01-22T10:30:12.000Z"
        }
      ]
    },
    "completedAt": "2026-01-15T10:30:12.000Z"
  }
}

Idempotencia

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).

http
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhooks

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.
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

Verificar un webhook (Node.js)

javascript
import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return signature === expected;
}

app.post("/hook", (req, res) => {
  const sig = req.header("X-Webhook-Signature");
  if (!verify(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  // req.body: { taskId, serviceCode, status, ... }
  res.status(200).end();
});

Créditos y facturació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.
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/cost \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"width": 1024, "height": 768}}'
json
{
  "success": true,
  "data": {
    "estimatedCredits": 10,
    "pricingType": "custom",
    "pricingMode": "dimension",
    "sufficient": true
  }
}

Límites de tasa

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.

CabeceraDescripción
X-RateLimit-Limit-MinuteSolicitudes permitidas por minuto.
X-RateLimit-Remaining-MinuteSolicitudes restantes en la ventana del minuto actual.
X-RateLimit-Limit-DaySolicitudes permitidas por día.
X-RateLimit-Remaining-DaySolicitudes 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.

http
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997

Errores

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

EstadoSignificado
200Éxito: el resultado se devuelve en línea.
202Aceptado: se creó una tarea asíncrona; sondea o espera el webhook.
400Solicitud incorrecta: entrada no válida o endpoint equivocado para el modo de ejecución del servicio.
401No autorizado: clave de API ausente, mal formada o de tipo incorrecto.
402Pago requerido: créditos insuficientes.
403Prohibido: la clave o la cuenta no puede usar este servicio.
404No encontrado: tarea desconocida o una tarea que no es tuya.
429Demasiadas solicitudes: se superó el límite de tasa o de concurrencia.
500Error del servidor: vuelve a intentarlo; el trabajo (si lo hay) se reembolsa.

Códigos de error comunes

CódigoUbicaciónSignificado
INSUFFICIENT_CREDITSerrorCodeCréditos personales insuficientes para el trabajo.
INSUFFICIENT_ORG_CREDITSerrorCodeCréditos de la organización insuficientes para el trabajo.
ORG_API_KEY_REQUIREDdata.codeEste endpoint necesita una clave de API de empresa (X-API-Key).
INVALID_ORG_API_KEYdata.codeLa clave de empresa está ausente, mal formada o revocada.
INVALID_API_KEYdata.codeEl 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_ALLOWEDerrorCodeTu organización no está aprobada para este servicio.
ORG_DISABLEDdata.codeLa cuenta de la organización está deshabilitada.
CONCURRENCY_LIMIT_EXCEEDEDerrorCodeDemasiados trabajos concurrentes para tu organización.
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCodeEste servicio no está disponible a través de la API externa.
TASK_NOT_FOUNDerrorCodeNo existe esa tarea para esta clave.
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Documentación API

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.

Servicios disponibles

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.

EndpointDescripción
GET /ai/servicesLista los servicios a los que tu clave puede acceder.
GET /ai/external/services/{code}/specObtén la especificación de parámetros de un servicio.
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"