Documentación

Todo lo que necesitas para integrar IA Box en tu aplicación

Quick Start

Comienza a usar IA Box en 5 minutos:

from openai import OpenAI

client = OpenAI(
    base_url="https://clouds.com.bo/v1",
    api_key="sk-air-your-api-key-here"
)

response = client.chat.completions.create(
    model="openai/gpt-3.5-turbo",
    messages=[
        {"role": "user", "content": "¡Hola!"}
    ]
)

print(response.choices[0].message.content)

Tip: IA Box es compatible con la SDK de OpenAI, así que solo necesitas cambiar la URL base y tu API key.

Autenticación

IA Box soporta dos métodos de autenticación:

1. Header X-API-Key

curl -X POST https://clouds.com.bo/airouter/v1/chat/completions \
  -H "X-API-Key: sk-air-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{...}'

2. Bearer Token

curl -X POST https://clouds.com.bo/airouter/v1/chat/completions \
  -H "Authorization: Bearer sk-air-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{...}'

Endpoints Disponibles

POST /airouter/v1/chat/completions

Envía una solicitud de chat completion. Compatible con streaming (stream: true).

Parámetros:

model (required) - El modelo a usar
messages (required) - Array de mensajes
temperature (optional) - Creatividad (0-2)
max_tokens (optional) - Máximo de tokens

GET /airouter/v1/models

Obtén la lista de alias de modelos habilitados para tu cuenta (nunca expone el proveedor/backend real detrás de cada uno).

GET /airouter/user/info

Obtén tu saldo de créditos y estadísticas de uso de los últimos 30 días.

Respuesta:

{
  "email": "user@example.com",
  "name": "John Doe",
  "credit_balance": 42.35,
  "tokens_used_lifetime": 128450,
  "is_active": true,
  "last_request_at": "2026-08-24T00:30:00Z",
  "stats_30d": {
    "total_requests": 340,
    "total_tokens": 128450,
    "total_cost": 6.65,
    "success_rate": 99.1,
    "avg_response_time": 820,
    "most_used_model": "openai/gpt-4-turbo"
  }
}

GET /airouter/health

Verifica el estado del gateway (no requiere autenticación).

Ejemplos

JavaScript / TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://clouds.com.bo/v1',
  apiKey: 'sk-air-your-api-key-here',
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-3.5-turbo',
  messages: [{ role: 'user', content: 'Hola' }],
});

console.log(response.choices[0].message.content);

PHP

$ch = curl_init('https://clouds.com.bo/v1/chat/completions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer sk-air-your-api-key-here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'model' => 'openai/gpt-3.5-turbo',
    'messages' => [
        ['role' => 'user', 'content' => 'Hola']
    ]
]));

$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data['choices'][0]['message']['content'];

cURL

curl -X POST https://clouds.com.bo/airouter/v1/chat/completions \
  -H "Authorization: Bearer sk-air-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hola"}]
  }'

Manejo de Errores

401 - Autenticación Inválida

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Verifica que tu API key sea correcta y esté activa.

429 - Límite de Solicitudes Excedido

{
  "error": {
    "message": "Rate limit exceeded for this model. Try again shortly.",
    "type": "rate_limit_error",
    "code": "requests_per_minute_exceeded",
    "details": { "limit_per_minute": 30 }
  }
}

Superaste el límite de solicitudes por minuto para ese modelo. Espera unos segundos y reintenta.

402 - Saldo Insuficiente

{
  "error": {
    "message": "Insufficient credit balance. Please top up your account.",
    "type": "insufficient_credits",
    "code": "insufficient_credits",
    "details": { "credit_balance": 0 }
  }
}

Tu saldo de créditos llegó a $0. Recarga desde /iabox/pricing para seguir usando la API.

500 - Error del Servidor

{
  "error": {
    "message": "Server error",
    "type": "server_error"
  }
}

Algo salió mal en nuestro servidor. Por favor, intenta de nuevo o contacta a soporte.