Documentación de la API

Una API compatible con OpenAI para usar distintos modelos de IA. URL base: https://api.modeltex.fashion/v1

Quickstart

De cero a tu primera respuesta:

1. Creá tu cuenta (email y contraseña).
2. Cargá saldo desde Facturación (si todavía no está habilitado, el panel te lo avisa).
3. En API Keys, creá una key. Se muestra completa una sola vez.
4. Guardala en una variable de entorno: export MODELTEX_API_KEY="mtx_live_…"
5. Hacé tu primera llamada:

Consultá GET /v1/models para ver qué modelos están activos en este momento; el ejemplo usa modeltex-fast como nombre típico.

Si ya tenés código con el SDK de OpenAI, alcanza con definir OPENAI_BASE_URL=https://api.modeltex.fashion/v1 y OPENAI_API_KEY=mtx_live_….

Autenticación

Todas las solicitudes a /v1 llevan tu API Key como Bearer token:

Authorization: Bearer mtx_live_xxxx…

• Las keys empiezan con mtx_live_. Solo guardamos su huella (SHA-256); no podemos recuperarla si la perdés.
• Podés tener varias keys, deshabilitarlas, regenerarlas o revocarlas desde el panel. Cada una puede tener un límite de gasto mensual, un límite de solicitudes por minuto y una lista de modelos permitidos.
• Nunca pongas la key en código de navegador ni en repositorios públicos. Usala desde tu servidor.
• Una key inválida, revocada o deshabilitada responde 401 invalid_api_key.

Modelos Modeltex

Cada modelo es un alias de Modeltex (por ejemplo modeltex-fast, modeltex-smart, modeltex-pro, modeltex-reasoning). El motor real (proveedor y modelo de origen) lo gestiona Modeltex y puede cambiar sin que tu código cambie; la API nunca lo expone. Los modelos activos, sus capacidades y sus precios son los que devuelve la API:

Respuesta (formato OpenAI con un campo extra modeltex):

{
  "object": "list",
  "data": [
    {
      "id": "modeltex-fast",
      "object": "model",
      "created": 0,
      "owned_by": "modeltex",
      "modeltex": {
        "display_name": "Modeltex Fast",
        "context_window": 128000,
        "max_output_tokens": 8192,
        "capabilities": ["chat", "streaming"],
        "category": "general",
        "requires_subscription": false,
        "knowledge_enabled": false,
        "pricing_usd_per_1m_tokens": { "input": "0.15", "output": "0.60" }
      }
    }
  ]
}

Los valores de arriba son un ejemplo de formato, no precios reales. Los precios vigentes se leen de la API.

GET /v1/models/{id} devuelve un solo modelo. Si tu key tiene modelos restringidos, solo ves los permitidos.

Modelos especializados

Un modelo especializado es un modelo de lenguaje al que Modeltex le agrega conocimiento propio y reglas de comportamiento para una especialidad. Se usa exactamente igual que cualquier otro: cambiás el nombre del modelo.

Qué puede esperar de un modelo especializado: responde con tono y criterio de su especialidad, distingue lo que sale de la base de Modeltex de lo que es conocimiento general, avisa cuando la base no cubre tu pregunta y no afirma haber realizado pruebas, cortes o fittings. No reemplaza ensayos de laboratorio, normas obligatorias ni a un profesional.

Conocimiento y RAG

Cuando un modelo tiene conocimiento asociado, cada solicitud pasa por una recuperación (RAG) antes de llegar al motor:

1. Se toma tu último mensaje (y el anterior si es muy corto) como consulta.
2. Se buscan en la base de conocimiento los fragmentos más relevantes (búsqueda por texto y, si está configurada, también por embeddings).
3. Esos fragmentos se agregan como contexto, tratados como datos y no como instrucciones, junto con el comportamiento del modelo.
4. El modelo responde citando los fragmentos con [1], [2]… cuando los usa.

Facturación del contexto: el contexto recuperado cuenta como tokens de entrada y se cobra al precio de entrada del modelo (por eso el usage.prompt_tokens es mayor que el de tu mensaje).

Fuentes: podés pedirlas con el campo de extensión modeltex. Solo se devuelven si la base de conocimiento permite mostrarlas; nunca se devuelve el texto de los documentos.

Con metadata la respuesta incluye un objeto modeltex con request_id, model, cost_usd (lo que se te cobra), latency_ms y knowledge.used; con sources, además, knowledge.sources (documento, fragmento y puntaje) cuando corresponde. Nunca incluye costos ni datos del proveedor.

Tu contenido no se usa para alimentar las bases de conocimiento de Modeltex. Las bases privadas por cliente (planes Business) están contempladas en la arquitectura pero todavía no están habilitadas.

Chat Completions

POST /v1/chat/completions

Todavía no disponibles (la API responde 400 con el nombre del parámetro): functions (el formato viejo), function_call, logprobs, entradas de imagen o audio.

Respuesta:

{
  "id": "chatcmpl-req_…",
  "object": "chat.completion",
  "created": 1735689600,
  "model": "modeltex-fast",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "…" }, "finish_reason": "stop" }],
  "usage": {
    "prompt_tokens": 12, "completion_tokens": 34, "total_tokens": 46,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

El encabezado x-request-id identifica cada solicitud: citálo si necesitás soporte.

Streaming

Con "stream": true la respuesta llega como Server-Sent Events con chunks chat.completion.chunk y termina con data: [DONE]. Agregá "stream_options": {"include_usage": true} para recibir el uso en un chunk final. El cobro se hace al terminar el stream, con los tokens reales.

El respaldo entre proveedores solo ocurre antes de que empiece la respuesta; una vez iniciado el stream no cambia de proveedor.

Tool calling

Las herramientas (function calling) funcionan en formato OpenAI, solo en los modelos que declaran la capacidad tools en GET /v1/models (modeltex.capabilities). Si el modelo no la declara, la API responde 400 capability_not_supported: no se simula.

1. Enviás tools (y opcionalmente tool_choice) con tu mensaje.
2. Si el modelo decide usar una herramienta, responde con finish_reason: "tool_calls" y message.tool_calls.
3. Ejecutás la función vos y enviás el resultado en un mensaje con role: "tool" y el tool_call_id correspondiente.

Si el modelo tiene rutas de respaldo, solo se usan las que también soportan herramientas: el comportamiento no cambia por caprichos de ruteo. También funciona con streaming (los fragmentos llegan en delta.tool_calls).

Embeddings

POST /v1/embeddings — disponible cuando existe un modelo con la capacidad embeddings activo en tu catálogo. Parámetros: model, input (texto o lista de hasta 64 textos de hasta 8.000 caracteres) y opcionalmente encoding_format: "float". No admite dimensions ni base64 por ahora. La respuesta es la de OpenAI (data[].embedding, usage.prompt_tokens) y se factura por tokens de entrada.

Errores

Todos los errores tienen el mismo formato JSON, con el request_id de la solicitud:

{
  "error": {
    "message": "Saldo insuficiente para esta solicitud. Recargá tu saldo desde Facturación.",
    "type": "billing_error",
    "code": "insufficient_balance",
    "param": null,
    "request_id": "req_…"
  }
}

Las solicitudes que terminan en error no se cobran.

Rate limits

• Por defecto, 60 solicitudes por minuto por API Key. Tu plan puede definir otro valor, y podés fijar uno propio por key (el de la key manda).
• Un modelo puede tener además su propio límite por minuto.
• Al superarlo recibís 429 con el encabezado Retry-After (segundos). Esperá ese tiempo y reintentá.
• Las solicitudes rechazadas por límite no se cobran ni reservan saldo.
• Muchos intentos con keys inválidas desde una misma IP también se limitan.

Facturación

• Prepago en USD. Cargás saldo y se descuenta por uso. Los montos se manejan en enteros de alta precisión (nano-dólares), sin errores de redondeo de coma flotante.
• El precio es por millón de tokens, con tarifas separadas para entrada y salida (y, cuando el modelo lo define, para tokens cacheados y de razonamiento).
• Reserva y cobro real: antes de llamar al modelo se calcula el costo máximo posible (tus tokens de entrada estimados + max_tokens) y se reserva. Con la respuesta se leen los tokens reales, se cobra eso y se libera la diferencia. Por eso un saldo muy bajo puede rechazar una solicitud con max_tokens alto: bajalo o recargá.
• Idempotencia: enviá Idempotency-Key: <valor-único> para que un reintento de la misma operación no se cobre dos veces (la repetición devuelve 409).
• Cada llamada y cada movimiento quedan en Uso, Requests y Facturación. No guardamos tus prompts ni las respuestas.
• Alertas de saldo en el panel: cuando baja del 20 % de tu última recarga, de US$ 5, de US$ 1 o se agota.

Suscripciones

Podés combinar suscripción + créditos + pay-as-you-go:

• Pay-as-you-go: cargás saldo (US$ 5, 10, 20, 50 u otro monto) y pagás por uso. Siempre disponible.
• Plan de suscripción: se paga con tu saldo (se descuenta el precio y se acredita el crédito incluido) y se renueva cada período mientras haya saldo. Puede incluir modelos que requieren suscripción, límites de solicitudes por minuto y de API Keys propios.
• Si al renovar no alcanza el saldo, el plan pasa a en mora (sin beneficios) y se reintenta; tras 7 días se cancela. Podés cancelar cuando quieras: seguís con los beneficios hasta el final del período.
• Auto-recarga: podés dejar configurado umbral y monto. El cobro automático requiere un método de pago guardado que todavía no está habilitado; mientras tanto el panel te avisa en lugar de cobrar.

Los precios y características de los planes los publica Modeltex en Facturación; esta documentación no fija valores.

Ejemplos

Streaming

Con instrucciones de sistema y reintento seguro

Compatibilidad con OpenAI

Para migrar un proyecto existente: cambiá OPENAI_BASE_URL y OPENAI_API_KEY, y reemplazá el nombre del modelo por un alias de Modeltex.