Verbo AI — Documentación API

Conectá tu app, bot o script a Verbo AI usando un token verboai-XXXX

🧪 Probar la API en vivo

Pegá tu token y un mensaje. Podés probar generar imágenes escribiendo "Generame [algo]" con NewserAvanced.

Los resultados van a aparecer acá...

1. Obtener un token

Para usar la API necesitás un token tipo verboai-XXXXXXXXXXXX. Para conseguirlo:

Entrá a la app e iniciá sesión
Andá a Settings → Clave API
Hacé clic en "Generar API token"
Copialo AHORA: solo se muestra una vez, después solo ves los últimos 4 dígitos

Si no ves la sección "Clave API" en Settings, tu cuenta todavía no tiene acceso (mensaje "Próximamente"). Pedile al admin que te agregue.

2. Endpoints disponibles

`POST /api/v1/chat` principal

Envía un mensaje y recibe la respuesta. Consume créditos según el modelo.

curl -X POST https://verboai.duckdns.org/api/v1/chat \
  -H "Authorization: Bearer verboai-XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "mensaje": "Hola, quien eres?",
    "modelo": "NewserLite"
  }'

Respuesta:

{
  "ok": true,
  "respuesta": "Hola, soy NewserLite...",
  "modelo": "NewserLite",
  "modeloUsado": "NewserLite",
  "costoCreditos": 1,
  "creditosRestantes": 999,
  "rateLimitMax": 20,
  "rateLimitVentanaMs": 60000
}

`GET /api/v1/info` gratis

Devuelve info del token (créditos restantes, modelos disponibles). No consume créditos.

curl -H "Authorization: Bearer verboai-XXXX" \
  https://verboai.duckdns.org/api/v1/info

`GET /api/mongo-status` admin

Verifica el estado de MongoDB (requiere sesión iniciada).

3. Modelos disponibles

NewserLite

Rápido y liviano
1 crédito/pedido
20 req/min (API)
30 req/min (web)

NewserAvanced

Potente + imágenes
5 créditos/pedido
5 req/min (API)
8 req/min (web)

Si mandás un "modelo" inválido o vacío, cae automáticamente a NewserLite (no rompe).

4. Generar imágenes con IA 🎨

Si el mensaje empieza con Generame, Genera, Dibujame, etc., se genera una imagen con IA automáticamente (sin pasar por el modelo de texto). Solo funciona con NewserAvanced.

Consume +1 crédito adicional (encima del costo del modelo)
La imagen se devuelve como URL en el campo imagen.url
La URL es relativa: /uploads/xxxxx.jpg — hay que prependear el dominio

curl -X POST https://verboai.duckdns.org/api/v1/chat \
  -H "Authorization: Bearer verboai-XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "mensaje": "Generame un leon descansando al atardecer",
    "modelo": "NewserAvanced"
  }'

Respuesta:

{
  "ok": true,
  "respuesta": "Imagen generada: un leon descansando al atardecer",
  "modelo": "NewserAvanced",
  "costoCreditos": 6,
  "costoBase": 5,
  "costoExtraHerramientas": 1,
  "imagen": {
    "url": "/uploads/1234567890-abcdef.jpg",
    "prompt": "un leon descansando al atardecer",
    "tamanoKB": 102
  },
  "creditosRestantes": 994
}

Para descargar la imagen, prependeá el dominio: https://verboai.duckdns.org/uploads/1234567890-abcdef.jpg

5. Código completo para tu app

Copiá el que corresponda a tu lenguaje. Reemplazá verboai-XXXX por tu token.

JavaScript (Node.js 18+ o navegador)

const TOKEN = "verboai-XXXX";
const URL = "https://verboai.duckdns.org/api/v1/chat";

async function preguntar(mensaje, modelo = "NewserLite") {
  const resp = await fetch(URL, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ mensaje, modelo }),
  });
  const data = await resp.json();
  if (!data.ok) throw new Error(data.error);
  return data;
}

// Ejemplo: chat básico
const r = await preguntar("Hola, quien eres?", "NewserLite");
console.log(r.respuesta, "créditos:", r.creditosRestantes);

// Ejemplo: generar imagen
const r2 = await preguntar("Generame un leon", "NewserAvanced");
if (r2.imagen) {
  const url = "https://verboai.duckdns.org" + r2.imagen.url;
  console.log("Imagen:", url);
}

Python 3.7+ (sin dependencias)

import json
import urllib.request

TOKEN = "verboai-XXXX"
URL = "https://verboai.duckdns.org/api/v1/chat"

def preguntar(mensaje, modelo="NewserLite"):
    body = json.dumps({"mensaje": mensaje, "modelo": modelo}).encode()
    req = urllib.request.Request(URL, data=body, method="POST")
    req.add_header("Authorization", f"Bearer {TOKEN}")
    req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req, timeout=120) as resp:
        data = json.loads(resp.read().decode())
    if not data.get("ok"):
        raise Exception(data.get("error"))
    return data

# Ejemplo: chat básico
r = preguntar("Hola, quien eres?", "NewserLite")
print(r["respuesta"], "creditos:", r["creditosRestantes"])

# Ejemplo: generar imagen
r = preguntar("Generame un leon", "NewserAvanced")
if r.get("imagen"):
    print("Imagen:", "https://verboai.duckdns.org" + r["imagen"]["url"])

PHP 5.6+ (con cURL)

<?php
$TOKEN = "verboai-XXXX";
$URL = "https://verboai.duckdns.org/api/v1/chat";

function preguntar($mensaje, $modelo = "NewserLite") {
    global $TOKEN, $URL;
    $body = json_encode(["mensaje" => $mensaje, "modelo" => $modelo]);
    $ch = curl_init($URL);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $TOKEN",
        "Content-Type: application/json",
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 120);
    $resp = curl_exec($ch);
    curl_close($ch);
    return json_decode($resp, true);
}

// Ejemplo
$r = preguntar("Hola, quien eres?", "NewserLite");
echo $r["respuesta"] . "\n";
?>

cURL (bash / terminal)

# Chat básico
curl -X POST https://verboai.duckdns.org/api/v1/chat \
  -H "Authorization: Bearer verboai-XXXX" \
  -H "Content-Type: application/json" \
  -d '{"mensaje":"Hola, quien eres?"}'

# Con NewserAvanced
curl -X POST https://verboai.duckdns.org/api/v1/chat \
  -H "Authorization: Bearer verboai-XXXX" \
  -H "Content-Type: application/json" \
  -d '{"mensaje":"Explicame el libro de Job","modelo":"NewserAvanced"}'

# Generar imagen
curl -X POST https://verboai.duckdns.org/api/v1/chat \
  -H "Authorization: Bearer verboai-XXXX" \
  -H "Content-Type: application/json" \
  -d '{"mensaje":"Generame un leon","modelo":"NewserAvanced"}'

# Info del token (no gasta créditos)
curl -H "Authorization: Bearer verboai-XXXX" \
  https://verboai.duckdns.org/api/v1/info

6. Códigos de error

401 — Token inválido, revocado, o falta el header Authorization
402 — No tenés créditos suficientes (ej: NewserAvanced necesita 5)
429 — Rate limit alcanzado (demasiados pedidos por minuto)
400 — Body mal formado o falta "mensaje"
502 — El proveedor de IA no responde (probá de nuevo en unos minutos)

7. CLI de terminal (opcional)

Si preferís usar Verbo AI desde la terminal, descargá el archivo cli/verboai.py del repositorio y ejecutá:

# Guardar el token (una sola vez)
python verboai.py login verboai-XXXX

# Iniciar chat interactivo
python verboai.py run

# Ver info del token
python verboai.py info

El CLI levanta un servidor proxy local en http://127.0.0.1:7788 (alta seguridad, el token no se expone). Comandos dentro del chat: /modelo, /creditos, /info, /salir.