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.

Recorte avanzado

super-matting

Recorte de alta calidad que separa un sujeto de su fondo y devuelve un resultado de recorte limpio. Asíncrono: envía y, después, sondea o espera un webhook.

Precios

Se cobra según el borde de salida más largo (tramos por dimensión; p. ej., 512 px son 2 créditos y 1024 px, 10). Llama al endpoint /cost para conocer el importe exacto antes de ejecutar un trabajo.

Parámetros

ParámetroTipoObligatorioDescripción
source_typestringSíUno de "url" (input_value es una URL http(s) pública de imagen) o "base64" (input_value es una cadena base64 o una data: URL).
input_valuestringSíLa imagen de origen: una URL http(s) cuando source_type es "url", o datos de imagen en base64 cuando source_type es "base64".
widthnumberSíAncho objetivo en píxeles (64–2048).
heightnumberSíAlto objetivo en píxeles (64–2048).
seednumberNoOpcional. Semilla entera fija para una salida reproducible; si se omite, se usa una semilla aleatoria.

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(s) imagen(es) de salida del recorte.

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"
  }
}

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/super-matting/execute
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/execute \
  -H "X-API-Key: vber_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_type": "url",
      "input_value": "https://example.com/photo.png",
      "width": 1024,
      "height": 768
    }
  }'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"