HopBase DocsReferencia de la API
Base URL de la API de HopBase, autenticación con claves por grupo, ID de solicitud, estructura de errores y límites de concurrencia, más la lista completa de endpoints.
HopBase es un gateway de API multimodelo: chat, imágenes, video y voz se llaman a través del mismo dominio https://api.hop-base.com, con los formatos oficiales de OpenAI y Anthropic, así que los SDK existentes solo necesitan cambiar el Base URL y la clave. Esta sección tiene una página por endpoint, y las tablas de parámetros y los ejemplos se generan a partir de la descripción OpenAPI.
Lista de endpoints
/v1/chat/completionsCrear una completion de chatPOST/v1/responsesCrear una respuestaPOST/v1/messagesCrear un mensaje/v1/images/generationsGenerar imágenesPOST/v1/images/editsEditar imágenesGET/v1/images/tasksConsultar una tarea de imagen/v1/video/generateEnviar una tarea de videoGET/v1/video/tasks/{task_id}Consultar una tarea de videoGET/v1/video/tasksListar tareas de videoPOST/v1/kling/subjectsCrear un sujeto personalizadoGET/v1/kling/subjectsConsultar sujetos personalizadosPOST/v1/kling/facesReconocimiento facial para sincronización labial/v1/audio/speechCrear vozPOST/v1/t2a_v2Crear audio T2A v2POST/v1/files/uploadSubir audio para clonarGET/v1/files/listListar audios para clonarGET/v1/files/retrieveConsultar audio para clonarPOST/v1/files/deleteEliminar audio para clonarPOST/v1/voice_cloneCrear una voz clonadaPOST/v1/get_voiceListar vocesPOST/v1/delete_voiceEliminar vozBase URL
| Protocolo | Base URL | Para |
|---|---|---|
| Compatible con OpenAI | https://api.hop-base.com/v1 | Chat, Responses, imágenes, video, voz, /v1/models, /v1/usage |
| Anthropic | https://api.hop-base.com | /v1/messages de los modelos Claude (en el SDK, sin /v1) |
El protocolo depende del cliente y del tipo de modelo, no del formato de la clave. La correspondencia completa por escenario (Claude Code, Codex CLI, cada familia de modelos) está en Base URL y protocolos. Wan / HappyHorse usan la ruta de video nativa /api/v1/services/aigc/video-generation/video-synthesis, en la raíz del dominio.
Autenticación
Todos los endpoints se autentican con una clave sk- creada en Claves API de la consola, con cualquiera de estas dos cabeceras:
Authorization: Bearer sk-tu-clave
x-api-key: sk-tu-claveNo se admiten x-goog-api-key ni el parámetro de URL ?key=. GET /v1/usage solo acepta Authorization: Bearer.
Cada clave está vinculada a un grupo (por ejemplo "Codex Pro", "Claude Max (oficial, cuota completa)" o "GPT Image (todos los modelos)") y solo puede llamar a los modelos de ese grupo y a los endpoints de su protocolo: una clave Claude en /v1/chat/completions devuelve 404 "The current platform does not support this API path", y una clave de un grupo de chat que llama a un modelo de imagen devuelve 404 model_not_found. Si un mismo proyecto necesita chat y generación de imágenes, cree dos claves y guárdelas en variables de entorno distintas. Los modelos disponibles son los que devuelve GET /v1/models con esa clave.
Inyecte la clave mediante variables de entorno o su plataforma de despliegue; no la escriba en el código fuente ni la suba a Git.
ID de solicitud
Cada respuesta incluye la cabecera x-request-id, el identificador único de esa solicitud. Al reportar un problema, adjunte x-request-id, la hora en que ocurrió (con zona horaria), el ID del modelo y el texto completo del error: los fallos del servidor no muestran el texto original en la consola, así que la investigación se basa en x-request-id.
curl -i https://api.hop-base.com/v1/models \
-H "Authorization: Bearer $HOPBASE_API_KEY"
# HTTP/2 200
# x-request-id: …Algunas respuestas de modelos traen sus propias cabeceras de límite de tasa (x-ratelimit-*, anthropic-ratelimit-*); no describen los límites de su cuenta ni de su clave, así que no limite el ritmo en función de ellas.
Errores
Los endpoints del protocolo OpenAI devuelven {"error": {"message", "type", "code"}}; /v1/messages devuelve la estructura de Anthropic {"type": "error", "error": {"type", "message"}}, sin code. El idioma del mensaje sigue Accept-Language y, si no se indica, es inglés; en su código, decida por el código de estado HTTP y code, no compare el texto.
| Código de estado | Significado | ¿Se puede reintentar? |
|---|---|---|
| 400 / 413 | Parámetros no válidos / el cuerpo de la solicitud supera 60 MB | No; corrija antes la solicitud |
| 401 | Falta la clave, no es válida o ha caducado | No |
| 402 | Se agotó el saldo o la cuota; al enviar video, el saldo no cubre las reservas en curso | Después de recargar |
| 403 | Cuenta o miembro desactivado, o sin permiso para usar ese grupo | No |
| 404 | El modelo o la ruta no pertenecen al grupo de esta clave | No |
| 429 | Se alcanzó el límite de concurrencia de la cuenta o de la clave, o el servicio está ocupado | Reintente según Retry-After |
| 502 / 503 / 504 | Servicio no disponible temporalmente o tiempo agotado | Reintente con espera creciente |
Una vez que una solicitud en streaming empieza a emitir salida, el estado HTTP ya es 200 y los errores posteriores llegan como eventos; ver Eventos de streaming. La lista completa de códigos de error y las reglas de reintento están en Códigos de error y reintentos.
Concurrencia y límites de tasa
HopBase limita por número de solicitudes en curso a la vez, no por solicitudes por minuto: por defecto, una cuenta puede tener 5 solicitudes en curso a la vez, ampliable bajo petición; cada clave puede tener su propio límite en la consola, y se aplica el menor de los dos. Las solicitudes que lo superan devuelven 429 de inmediato (user_concurrency_limit / apikey_concurrency_limit, con Retry-After: 1 y Retry-After-Ms); no se encolan en el servidor.
El chat, la generación de imágenes, el envío de video y /v1/messages/count_tokens consumen concurrencia; la consulta de tareas y GET /v1/models no. Los criterios de tiempo de espera y los tiempos de lectura recomendados en el cliente están en Concurrencia, tiempos de espera y facturación.
Facturación
Las solicitudes correctas se facturan según la unidad de precio del modelo (token / imagen / segundo / carácter); en principio, los fallos no se facturan, un stream interrumpido se factura por la parte ya generada y las tareas asíncronas fallidas no se facturan. Consulte el saldo con GET /v1/usage; los precios oficiales de lista están en el catálogo público GET /api/v1/models/pricing (descripción de campos).
Descripciones legibles por máquina
/openapi.json: descripción OpenAPI 3.1 de todos los endpoints de esta sección; se puede importar en Postman, Apifox o generadores de SDK./spec/models/index.json: un JSON Schema del cuerpo de la solicitud por cada modelo de generación de imágenes, con los números tomados del código de validación del gateway.- Constructor de solicitudes: arma en el navegador una solicitud de generación de imágenes válida para cada modelo y genera el código.