API de cuenta y catálogo

Ninguno de estos endpoints se factura y ninguno exige saldo positivo.

Listar modelos

GET /v1/models acepta Authorization: Bearer sk-… o x-api-key: sk-…; GET /v1/usage solo acepta Authorization: Bearer sk-….

curl https://api.hop-base.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

La lista contiene solo los modelos de los grupos que incluye la clave (si tiene varios, la unión de todos) y llega completa en una sola respuesta (sin paginación). Las claves de grupos compatibles con OpenAI reciben una lista con formato OpenAI:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-6-astra",
      "object": "model",
      "created": 1790222400,
      "owned_by": "hopbase",
      "capabilities": ["chat", "reasoning"],
      "context_window": 1050000,
      "context_length": 1050000,
      "max_input_tokens": 1050000,
      "max_output_tokens": 128000
    }
  ]
}

Las claves de grupos Claude reciben el formato de Anthropic:

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-5-5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Sonnet 5.5",
      "created_at": "2026-09-28T00:00:00Z"
    }
  ],
  "has_more": false,
  "first_id": "claude-sonnet-5-5",
  "last_id": "claude-haiku-4-5-20251001"
}

has_more, first_id y last_id existen solo por compatibilidad con los SDK: la lista nunca se pagina, así que no pagine con ellos. Algunos modelos pueden no traer campos distintos de id; trate los campos desconocidos como opcionales.

Moneda del saldo: USD

Desde el 2026-10-01, el saldo de la cuenta, las cuotas de las claves, los cargos y los registros de consumo se expresan en dólares estadounidenses (USD): los modelos se cobran al precio oficial en USD multiplicado por la tarifa de su grupo, y tanto la consola como GET /v1/usage muestran importes en USD.

• Saldo existente: se convirtió a USD con una tasa fija, así que lo que puede gastar no cambió. Los precios de los grupos y las claves tampoco cambiaron.
• Cargos por solicitud: para que las integraciones existentes sigan funcionando, cost y X-HopBase-Cost en las respuestas siguen siendo el mismo cargo en CNY (con hasta 6 decimales) y currency siempre es CNY. El importe en USD que se descuenta realmente de su saldo está en cost_usd y X-HopBase-Cost-USD, y coincide con Consumo. Vea Cargos.
• Recargas: la moneda de pago, las comisiones y el importe acreditado son los que muestra la página Recarga antes de pagar; las comisiones se indican por separado y no se acreditan. En las transferencias bancarias de empresa y las recargas fuera de línea en CNY, el importe en USD que se acredita lo confirma el equipo de soporte.

Saldo y cuota

curl https://api.hop-base.com/v1/usage \
  -H "Authorization: Bearer sk-your-key"

Una clave con una cuota de $10, de la que se han usado $2:

{
  "is_active": true,
  "balance": 8,
  "remaining": 8,
  "unit": "USD",
  "ledger_currency": "USD",
  "balance_cny": 54.4,
  "balance_usd": 8,
  "quota": {
    "remaining": 8,
    "api_key_remaining": 8,
    "total": 10,
    "used": 2,
    "unlimited": false,
    "remaining_cny": 54.4,
    "remaining_usd": 8,
    "api_key_remaining_cny": 54.4,
    "api_key_remaining_usd": 8,
    "total_cny": 68,
    "total_usd": 10,
    "used_cny": 13.6,
    "used_usd": 2
  }
}

Cómo se calcula balance:

• Clave sin cuota propia: el saldo de la cuenta.
• Clave con cuota: la cuota que le queda.
• Las claves de miembros de equipo y departamentos se limitan además a la cuota restante del periodo del miembro y del departamento.

Los importes sin sufijo son balance, remaining, quota.remaining, quota.api_key_remaining, quota.total y quota.used.

Cada importe tiene además un campo en CNY y otro en USD con sufijo:

Una clave con cuota propia sigue descontando del saldo de la cuenta: si la cuenta se queda sin saldo antes, las solicitudes devuelven 402 aunque aquí balance muestre cuota disponible.

Este endpoint no usa el cuerpo de error estándar. Los fallos tienen este aspecto:

El cuerpo completo del primer caso 401:

{"is_active": false, "balance": 0, "message": "missing or invalid api key"}

Los dos casos 200 también incluyen ledger_currency y balance_cny / balance_usd (ambos 0).

Decida según is_active, no solo según el estado HTTP. Para el detalle de cada cargo, abra Consumo en la consola.

Cargos por solicitud, tarea y registro

Las solicitudes síncronas y las tareas asíncronas informan cada cargo en dos monedas: cost_usd es el importe en USD que se descuenta realmente de su saldo, el mismo que el registro en Consumo de la consola; cost es el mismo cargo en CNY y se mantiene en CNY para que las integraciones existentes sigan funcionando, por eso currency siempre es CNY. cost_usd tiene hasta 8 decimales; cost se redondea a 6.

Solicitudes síncronas (chat, imágenes, voz)

Una solicitud síncrona facturada devuelve su cargo real en tres encabezados de respuesta:

Una respuesta JSON sin streaming también incluye los mismos cost, cost_usd y currency en el usage de nivel superior:

{
  "id": "chatcmpl-abc",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "ok" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 1, "total_tokens": 10, "cost": 0.001197, "cost_usd": 0.000176, "currency": "CNY" }
}

• Si la respuesta no tiene usage, se añade uno, como en la respuesta JSON de síntesis de voz POST /v1/t2a_v2. Los campos que ya tenía usage, como cost_in_usd_ticks de xAI, no cambian.
• Si usage ya tiene cost, cost_usd o currency, o no es un objeto, el cuerpo se deja igual. Lea los encabezados.
• Las respuestas binarias, como el audio de síntesis de voz, solo llevan los encabezados.
• Las respuestas en streaming (SSE) no llevan ninguno: los encabezados se envían antes de que empiece la generación y el evento final de uso se reenvía sin cambios. Consulte el cargo de una solicitud en streaming en Uso de la consola.
• Cuando la generación de una imagen tarda más de unos 40 segundos, el servidor envía primero los encabezados 200 y luego escribe espacios en blanco para mantener la conexión, así que los encabezados no llevan el cargo. Lea usage.cost / usage.cost_usd en el cuerpo.
• Las respuestas sin cargo, como las listas de modelos y los errores no facturados, no llevan ninguno. Si una solicitud fallida se factura igualmente, su respuesta de error lleva los encabezados y el cuerpo del error no cambia.
• Cuando HopBase reintenta una solicitud automáticamente, solo se factura el intento que se completa, y ese es el importe que se informa. Una clave con varios grupos se cobra según el grupo que atendió la solicitud.
• En una clave con multiplicador de venta, el importe es lo que se descontó de su saldo, sin el margen.
• Si el cliente se desconecta antes de recibir la respuesta, la solicitud se factura igualmente por lo que se usó; el cargo aparece en Uso.

Consultas de tareas asíncronas (imagen y video)

Cuando la tarea termina, el usage de nivel superior incluye cost_usd (el importe en USD que se descuenta realmente de su saldo por esta tarea), cost (el mismo cargo en CNY) y currency (la moneda de cost, siempre CNY). 0 significa un fallo sin cargo; al consultar una sola tarea, solo la clave que la creó ve estos campos.

{
  "id": "vt-1",
  "status": "completed",
  "usage": { "cost": 3.4, "cost_usd": 0.5, "currency": "CNY" }
}

En las listas de tareas (como GET /v1/video/tasks sin ID de tarea), cada tarea finalizada lleva los mismos cost, cost_usd y currency en su usage. Las listas abarcan toda la cuenta, así que las tareas creadas con otras claves de la misma cuenta también llevan el importe.

Registros de consumo en la consola

La página Consumo lee GET /api/v1/user/usage y GET /api/v1/user/usage/stats (sesión de la consola, no una clave sk-).

Cada registro incluye ledger_currency (USD desde el 2026-10-01), cost_cny y cost_usd: el importe cobrado por ese registro en CNY y en USD. La página muestra USD.

Las estadísticas incluyen ledger_currency, total_charged_cny y total_charged_usd, y cada elemento de by_model, by_key, by_group, by_department y by_member incluye cost_cny / cost_usd.

El campo antiguo total_cost de las estadísticas es el precio oficial de lista en USD antes de la tarifa de su grupo, no lo que se le cobró; para el cargo use total_charged_*.

Catálogo público de modelos

curl https://api.hop-base.com/api/v1/models/pricing

No requiere clave. La respuesta admite solicitudes de origen cruzado desde cualquier sitio y puede almacenarse en caché hasta 5 minutos (Cache-Control: public, max-age=300). Los precios son los de lista en USD antes de la tarifa de su grupo; lo que usted paga realmente por cada modelo aparece en el catálogo de modelos con la sesión iniciada.

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "platform": "openai",
      "models": [
        {
          "id": "gpt-6-astra",
          "name": "GPT-6 Astra",
          "context_window": 1050000,
          "capabilities": ["chat", "reasoning"],
          "vendor": "openai",
          "category": "chat",
          "input": 10,
          "cached_input": 1,
          "output": 50,
          "long_context": {
            "threshold": 272000,
            "input_multiplier": 2,
            "cached_multiplier": 2,
            "output_multiplier": 1.5
          },
          "price_unit": "token"
        }
      ]
    },
    {
      "platform": "minimax",
      "models": [
        {
          "id": "speech-2.8-hd",
          "name": "MiniMax Speech 2.8 HD",
          "capabilities": ["tts"],
          "vendor": "minimax",
          "series": "minimax-speech",
          "category": "audio",
          "input": 100,
          "output": 0,
          "price_unit": "character"
        }
      ]
    }
  ]
}

platform es, por ejemplo, openai, claude, gemini o kling; para el fabricante del modelo, vea vendor.

Por encima de threshold tokens de entrada, toda la solicitud se factura con input_multiplier / cached_multiplier / output_multiplier.

Los tramos de video_tokens son resolución, audio y medios de referencia. La unidad es por 1M de tokens de video con token y por segundo con second. El nombre de la clave es histórico.

Un modelo puede aparecer bajo más de un platform cuando se ofrece en más de un grupo. Pueden añadirse campos nuevos; ignore los que no reconozca.

Encabezados de respuesta

HopBase no envía encabezados con su límite de concurrencia, las solicitudes en curso ni el saldo restante. Use GET /v1/usage para el saldo y consulte Concurrencia, tiempos de espera y facturación para los límites. Algunas respuestas de modelos traen sus propios encabezados de límite de tasa (x-ratelimit-*, anthropic-ratelimit-*); no describen los límites de su cuenta ni de su clave, así que no regule el tráfico con ellos.

Próximos pasos

• Concurrencia, tiempos de espera y facturación: límites de concurrencia, tiempos de espera y reglas de facturación
• Códigos de error y reintentos: qué significa cada código de error y si conviene reintentar
• Modelos disponibles: consulte los ID de modelo disponibles para una clave