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.

Eliminación de fondo

ai-image-bg-remove

Elimina el fondo de una imagen y devuelve un recorte con fondo transparente. Asíncrono: envía y, después, sondea o espera un webhook.

Precios

Un cargo fijo por imagen. Llama al endpoint /cost para conocer el importe exacto.

Parámetros

ParámetroTipoObligatorioDescripción
imageUrlstringSíURL http(s) pública de la imagen a procesar. Es la única entrada que admite el servicio: no acepta base64 ni un source_type.
widthnumberNoOpcional. Solo se usa como valor de reserva del área de facturación cuando no se puede detectar la resolución de origen; no cambia la salida.
heightnumberNoOpcional. Solo se usa como valor de reserva del área de facturación cuando no se puede detectar la resolución de origen; no cambia la salida.

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.

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

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.

Una tarea pasa por estos valores. Deja de sondear en cuanto alcances un status terminal: completed, failed, cancelled o timeout.

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

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.

Una vez completada, result.assets contiene la imagen del recorte con fondo transparente.

Tarea completada

json
{
  "success": true,
  "data": {
    "taskId": "6a97e277a148c970dd545f40",
    "serviceCode": "ai-image-bg-remove",
    "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"
  }
}

Webhooks

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.

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.

POST/ai/services/ai-image-bg-remove/execute
bash
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"}}'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"