Integración con la API de Zhiqian LLM

¿Solo quieres saber precios y recarga?

Esta página es para desarrolladores que llaman desde un programa. Si solo usas el modelo grande dentro de ZQAgent, no necesitas solicitar una Key ni leer esta página; consulta Zhiqian LLM (precios y recarga).

La API de Zhiqian LLM es una pasarela de modelos compatible con OpenAI. Con una Key y una dirección puedes llamar a DeepSeek, Qwen, Xiaomi MiMo y otros modelos de origen, sin integrar ni recargar por separado en cada proveedor.

Si tu proyecto ya usa el SDK de OpenAI, normalmente solo hay que cambiar base_url y api_key.

Para quién es

Aplicaciones que necesitan una salida estable de modelos y no quieren depender de los límites o fallos de un solo proveedor
Equipos que comparten cuota y quieren liquidar por uso real, sin repartir muchas Keys a cada persona
Quien necesita consultar saldo, detalle de consumo e historial de recargas para costes o facturación externa

Inicio rápido

1. Obtener una API Key

Al registrarte en el centro de usuario se activa automáticamente la API de Zhiqian LLM y recibes 5 yuanes de crédito, sin solicitud aparte. En la página «API de Zhiqian LLM» del centro de usuario puedes:

Ver la Key: la página la enmascara por defecto; muestra el valor completo cuando lo necesites
Restablecer la Key: la anterior deja de ser válida al instante; la configuración del nodo se refresca en unos 5 segundos, así que espera antes de probar
Recargar por tu cuenta: compatible con WeChat Pay y Alipay

Si la página indica que hay que solicitar acceso, rellena el uso y el contacto; cuando se active, consulta la Key.

La Key es una cadena que empieza por sk-. Guárdala en un gestor de secretos; no la escribas en el repositorio ni en el frontend.

2. Enviar una petición

bash

curl https://zqai-api.cd-zq.com/v1/chat/completions \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zq-standard",
    "messages": [{"role": "user", "content": "Hola"}],
    "max_tokens": 128
  }'

3. Usar el SDK de OpenAI

PythonNode.js

python

from openai import OpenAI

client = OpenAI(
    base_url="https://zqai-api.cd-zq.com/v1",
    api_key="sk-tuKey",
)

resp = client.chat.completions.create(
    model="zq-standard",
    messages=[{"role": "user", "content": "Hola"}],
)
print(resp.choices[0].message.content)

javascript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://zqai-api.cd-zq.com/v1',
  apiKey: process.env.ZQAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: 'zq-standard',
  messages: [{ role: 'user', content: 'Hola' }],
});
console.log(resp.choices[0].message.content);

Información de conexión

Elemento	Valor
Base URL	`https://zqai-api.cd-zq.com/v1`
Autenticación	`Authorization: Bearer <API Key>`
Protocolo	HTTPS; streaming con `text/event-stream`
Especificación OpenAPI	openapi.yaml
Límite del body	32 MB (necesario al incrustar imágenes o audio en base64)

La especificación OpenAPI se puede importar directamente en Apifox, Postman o Swagger Editor, y sirve para generar SDK de cliente.

Interfaces

Se dividen en dos grupos que comparten la misma Key y el mismo saldo:

Grupo	Uso	Prefijo de ruta
Llamadas a modelos	Completado de chat, compatible con OpenAI	`/v1/chat/completions`, `/v1/models`
API genérica	Interfaces que no son de modelo, como OCR o consulta mercantil; se cobra por llamada	`/v1/proxy/{slug}/...`

Las consultas de cuenta y los movimientos de fondos sirven para ambos grupos.

Lista de modelos

http

GET /v1/models

Solo devuelve los alias de modelo a los que la Key actual tiene derecho.

json

{
  "object": "list",
  "data": [
    { "id": "zq-standard", "object": "model", "created": 0, "owned_by": "zqai" }
  ]
}

Completado de chat

http

POST /v1/chat/completions

Compatible con chat/completions de OpenAI; admite los campos habituales: messages, stream, max_tokens, temperature, top_p, stop, tools, tool_choice, response_format. En model se pone el alias de este servicio y la pasarela enruta automáticamente al origen correspondiente.

Llamada en streaming:

bash

curl -N https://zqai-api.cd-zq.com/v1/chat/completions \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zq-standard",
    "messages": [{"role": "user", "content": "Escribe una presentación de 50 palabras"}],
    "stream": true
  }'

La respuesta en streaming es igual que en OpenAI y termina con data: [DONE].

Consulta de cuenta

Con la misma Key se consultan los datos de tu propio inquilino; no hacen falta parámetros extra y no se pueden ver los de otros.

Interfaz	Uso
`GET /v1/account/balance`	Saldo disponible en tiempo real, congelado en curso y saldo del libro mayor
`GET /v1/account/usage`	Resumen de consumo, agregable por día o por modelo
`GET /v1/account/usage/records`	Detalle de consumo por petición
`GET /v1/account/recharges`	Número de recargas, recarga acumulada e historial

Movimientos de fondos

bash

curl "https://zqai-api.cd-zq.com/v1/account/transactions?kind=refund" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

Devuelve el flujo completo de recargas, consumos, reembolsos y ajustes; amount lleva signo (positivo para entradas, negativo para salidas) y también el resumen del periodo. Para conciliación y facturación es más completo que recharges.

bash

# Saldo
curl https://zqai-api.cd-zq.com/v1/account/balance \
  -H "Authorization: Bearer $ZQAI_API_KEY"

# Consumo de los últimos 7 días agregado por modelo
curl "https://zqai-api.cd-zq.com/v1/account/usage?group_by=model" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

# Últimos 20 registros de consumo
curl "https://zqai-api.cd-zq.com/v1/account/usage/records?limit=20" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

Ejemplo de respuesta de saldo:

json

{
  "object": "account.balance",
  "tenant_id": 1,
  "currency": "CNY",
  "available_micros": 12345678,
  "available": 12.345678,
  "reserved_micros": 0,
  "reserved": 0.0,
  "ledger_balance_micros": 12345678,
  "ledger_balance": 12.345678,
  "source": "redis",
  "as_of": "2026-10-20T12:00:00Z"
}

Diferencia entre los dos criterios de saldo:

Campo	Significado	Cuándo mirarlo
`available`	Libro caliente en Redis, ya descontado lo congelado en curso	Para decidir «¿puedo enviar otra petición?»
`ledger_balance`	Criterio del flujo en PG, sin congelados en curso	Conciliación y facturación

El consumo se agrega por ventanas antes de contabilizarse, así que ledger_balance puede ir 1–5 minutos por detrás del saldo en tiempo real; es un retraso normal de liquidación.

Unidad de importe

La respuesta da *_micros y yuanes. Para contabilizar dentro del programa usa enteros de microyuanes (1 yuan = 1 000 000 microyuanes); los campos en yuanes son solo para mostrar y no deben sumarse, o habrá errores de coma flotante.

Proxy de API genérica

Además de los modelos de chat, el gateway puede reenviar interfaces de upstream que no son de modelo: OCR, consulta de datos mercantiles, reconocimiento de voz, etc. Usan la misma Key y el mismo saldo, y la factura queda en un solo sitio.

El formato de los parámetros depende del servicio

El gateway solo reenvía, no convierte protocolos. Qué parámetros acepta un servicio y qué estructura devuelve depende del upstream que tenga detrás. Guíate por la documentación de interfaz que te entregue el equipo de operaciones: el {slug} y los cuerpos de petición de todos los ejemplos de abajo debes sustituirlos por los del servicio real.

Ver qué servicios hay

bash

curl https://zqai-api.cd-zq.com/v1/api-services \
  -H "Authorization: Bearer $ZQAI_API_KEY"

json

{
  "object": "list",
  "data": [
    {
      "slug": "ocr",
      "name": "OCR genérico",
      "billing_mode": "per_call",
      "unit_price": 0.01,
      "allowed_methods": ["POST", "GET"]
    }
  ]
}

Solo devuelve los servicios que tienes permiso de usar. slug es el segmento de la dirección de llamada, unit_price es el precio por llamada (en yuanes) y billing_mode se explica en las reglas de facturación de más abajo.

Cómo llamar

La parte que va detrás de /v1/proxy/{slug}/ se conecta tal cual al path del upstream:

text

Tu petición:      POST /v1/proxy/ocr/general?lang=zh
El upstream ve:   POST {dirección del upstream}/{ruta configurada}/general?lang=zh

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/general" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "iVBORw0KGgo..."}'

Las respuestas binarias se guardan directamente en disco, sin pasar antes por base64:

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/image" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -d '{"url": "https://example.com/a.jpg"}' \
  -o result.png

Para subir archivos también vale multipart; el gateway reenvía los bytes originales:

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/file" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -F "file=@invoice.pdf"

Diferencias con la interfaz de modelos

Aspecto	Modelos de chat	Proxy de API genérica
Ruta	`/v1/chat/completions`	`/v1/proxy/{slug}/...`
Cuerpo de la petición	Formato OpenAI fijo	Cualquiera (JSON / binario / multipart)
Respuesta	Formato OpenAI fijo	Se devuelve tal cual, la decide el upstream
Facturación	Por token	Por llamada
Streaming	SSE fotograma a fotograma	Paso directo (sin analizar fotogramas)

En común: la misma Key, el mismo saldo y el mismo control de tasa y auditoría.

Reglas de facturación

Modo	Significado	Cuándo se cobra
`per_call`	Precio fijo por llamada	En llamadas correctas (2xx) se cobra `unit_price`
`cost_markup`	Coste del upstream más un margen	En llamadas correctas se cobra «coste × (1 + margen)»
`free`	Sin coste	Solo se registra el uso; el saldo no cambia

Solo se cobra el éxito (2xx). Los errores del upstream y los fallos de red no se cobran.
Antes de llamar se reserva un importe; si falla, se devuelve íntegro.
Si el saldo no alcanza se devuelve 402 directamente, sin llamar antes al upstream para fallar después.

Aspectos a tener en cuenta

Tu Key no se envía al upstream. El gateway elimina las cabeceras Authorization, x-api-key y Cookie, y las sustituye por las credenciales que tenga configuradas para el upstream. Por eso el upstream ve la cuenta de la plataforma, no la tuya.

El método debe coincidir. Solo se pueden usar los métodos configurados para el servicio; si te equivocas devuelve 400 y el mensaje de error enumera los permitidos.

Los códigos de error son del gateway, no del upstream. Cuando el upstream devuelve 4xx/5xx, el gateway responde siempre 502 (code: upstream_error) y no propaga el código original: así no expone el estado de la cuenta ni los detalles de cuota del upstream.

Si algo falla, indica el ID de petición. Todas las respuestas llevan x-request-id en la cabecera, tanto en éxito como en error. Envíalo a operaciones y podrán localizar exactamente qué pasó en el upstream en esa llamada:

bash

curl -i -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/general" \
  -H "Authorization: Bearer $ZQAI_API_KEY" -d '{}' | grep -i x-request-id

Las cabeceras de respuesta se filtran. Las cabeceras hop-by-hop (connection, transfer-encoding, etc.) no se reenvían; el resto se conserva tal cual. El gateway añade dos cabeceras propias:

Cabecera de respuesta	Significado
`x-request-id`	ID de esta llamada, presente en éxito y error; facilítalo a operaciones al reportar
`x-charge-micros`	Cargo de esta llamada (micro-yuanes, 1 yuan = 1.000.000); 0 en modo `free`

Facturación

Se cobra por tokens reales y es de prepago: recargas antes; si el saldo no alcanza, la petición devuelve 402.

El precio depende del modelo; consulta Precios
El criterio es el mismo en streaming y sin streaming
Los fallos del origen y los parámetros incorrectos no se cobran; si el cliente corta a medias se cobra lo ya generado
Sin saldo no hay cola ni crédito: hay que recargar primero

Recarga por tu cuenta en la página «API de Zhiqian LLM» del centro de usuario (WeChat Pay / Alipay); el saldo está disponible al instante.

Códigos de error

Todos los errores usan el formato compatible con OpenAI:

json

{
  "error": {
    "message": "Saldo insuficiente",
    "type": "invalid_request_error",
    "param": null,
    "code": "insufficient_balance"
  }
}

HTTP	code	Significado	Qué hacer
400	`invalid_request`	Parámetros no válidos	Corrige la petición
401	`invalid_api_key`	Key ausente, no válida, caducada o desactivada	Revisa la Key
402	`insufficient_balance`	Saldo insuficiente	Recarga; reintentar no sirve
403	`forbidden`	Inquilino desactivado o Key sin permiso para ese modelo	Contacta con operaciones
404	`not_found`	Modelo o ruta inexistente	Revisa el alias del modelo
429	—	Límite de tasa alcanzado	Reintenta con retroceso
500	`internal_error`	Error interno del servicio	Reintenta más tarde; si persiste, contacta
502	`upstream_error`	Fallo del origen	Reintenta con retroceso
503	`capacity_exhausted`	Todos los canales saturados o cortacircuitos	Retrocede según `Retry-After`

503 incluye la cabecera Retry-After; espera el tiempo indicado y no reintentes de inmediato.

Preguntas frecuentes

¿Qué hago si pierdo la Key? En la página «API de Zhiqian LLM» del centro de usuario pulsa «Restablecer Key»; la anterior deja de ser válida al instante. En el servidor solo se guarda el hash, así que no se puede recuperar el valor original.

¿Puedo tener varias Keys? Actualmente una cuenta tiene una Key que comparte el mismo saldo. Para cambiarla usa «Restablecer Key»; la anterior quedará invalidada.

¿Debo gestionar yo los fallos del proveedor? No. La pasarela incluye degradación primario/respaldo y cortacircuitos: si el canal principal falla se cambia automáticamente al de respaldo, y solo cuando todos están caídos se devuelve 503. El cliente solo debe gestionar el reintento con retroceso ante 503.

¿Admite imágenes y llamadas a herramientas? Depende de la capacidad del modelo elegido. Si la petición incluye tools o imágenes, la pasarela solo enruta a canales que las admiten; si no hay ninguno disponible devuelve 400, sin degradar en silencio a solo texto.

¿Cuáles son los límites de concurrencia y frecuencia? Se configuran por Key y por defecto se comparten por inquilino. Si tienes necesidades claras de alta concurrencia, indícalo al activar el servicio y ajustaremos la cuota.

Enlaces relacionados

Especificación OpenAPI
Precios
Centro de usuario (cuenta, crédito, planes de dispositivos)

Integración con la API de Zhiqian LLM ​

Para quién es ​

Inicio rápido ​

1. Obtener una API Key ​

2. Enviar una petición ​

3. Usar el SDK de OpenAI ​

Información de conexión ​

Interfaces ​

Lista de modelos ​

Completado de chat ​

Consulta de cuenta ​

Movimientos de fondos ​

Proxy de API genérica ​

Ver qué servicios hay ​

Cómo llamar ​

Diferencias con la interfaz de modelos ​

Reglas de facturación ​

Aspectos a tener en cuenta ​

Facturación ​

Códigos de error ​

Preguntas frecuentes ​

Enlaces relacionados ​

Integración con la API de Zhiqian LLM

Para quién es

Inicio rápido

1. Obtener una API Key

2. Enviar una petición

3. Usar el SDK de OpenAI

Información de conexión

Interfaces

Lista de modelos

Completado de chat

Consulta de cuenta

Movimientos de fondos

Proxy de API genérica

Ver qué servicios hay

Cómo llamar

Diferencias con la interfaz de modelos

Reglas de facturación

Aspectos a tener en cuenta

Facturación

Códigos de error

Preguntas frecuentes

Enlaces relacionados