API: inteligencia artificial

Para qué sirve

Tu sistema puede usar la misma inteligencia artificial que atiende el WhatsApp del negocio, sin tener su propia cuenta con un proveedor: leer una foto o un PDF, redactar, resumir, corregir una plantilla de impresión… Lo que gaste se descuenta del saldo de tokens del negocio dueño de la clave, igual que las respuestas del bot.

Las rutas y los cuerpos son los de la API de Gemini (generateContent). Si tu código ya habla con Gemini, solo cambias la dirección y la clave.

El permiso de la clave

La clave necesita el permiso Usar la IA, que viene apagado. Lo enciende el dueño en Ajustes → Integraciones, en la clave, desde el panel o la app (ver Integraciones). Solo lo pueden tener las claves de acceso completo. Sin él, todas las rutas de /ai responden 403 ai_not_allowed, también las consultas: así probar la clave ya avisa.

Modelos

{
  "models": [
    {
      "name": "models/gemini-2.5-flash",
      "displayName": "gemini-2.5-flash (normal)",
      "outputTokenLimit": 65536,
      "supportedGenerationMethods": ["generateContent"]
    },
    {
      "name": "models/gemini-2.5-flash-lite",
      "displayName": "gemini-2.5-flash-lite (ligero, más barato)",
      "outputTokenLimit": 65536,
      "supportedGenerationMethods": ["generateContent"]
    }
  ]
}

Hay dos: el normal, el mismo con que atiende el bot (lee fotos y PDF y usa herramientas), y el ligero, más rápido y que gasta menos, para tareas sencillas. GET /ai/models/{modelo} devuelve la ficha de uno; con un modelo que no está en la lista, 404.

Pedir una respuesta

curl https://api.atiendefacil.com/api/v1/ai/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer af_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": { "parts": [{ "text": "Responde en español, en una frase." }] },
    "contents": [{ "role": "user", "parts": [{ "text": "Resume esta factura: ..." }] }],
    "generationConfig": { "temperature": 0.2 }
  }'

{
  "candidates": [
    {
      "content": { "role": "model", "parts": [{ "text": "Factura de 3 productos por 45,00 USD." }] },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": { "promptTokenCount": 41, "candidatesTokenCount": 12, "thoughtsTokenCount": 0 }
}

Cualquier otro campo se ignora. La respuesta es la de Gemini, tal cual. No se ofrece generar imágenes ni audio, subir archivos ni cachés.

El cuerpo admite hasta 30 MB. Límite: 30 peticiones por minuto y por clave.

Cuánto se cobra

Se cobra según lo que la IA reporta en usageMetadata:

• Lo que lee (promptTokenCount): un token de tu saldo por cada token.
• Lo que escribe y razona (candidatesTokenCount y thoughtsTokenCount): dos tokens de tu saldo por cada token, porque escribir le cuesta a la IA bastante más que leer.

Ejemplo: leer una plantilla de 10.000 tokens y devolverla corregida (10.000 más 2.000 de razonamiento) descuenta 10.000 + 24.000 = 34.000 tokens. Para gastar menos, usa el modelo ligero, pide respuestas cortas o baja el razonamiento con thinkingConfig.thinkingBudget.

En el historial de consumo del panel y de la app sale como IA usada desde la API · nombre de la clave. Una petición que la IA rechaza por mal formada no cobra nada.

Errores propios

Preguntas frecuentes