Chat de Gemini

Los dos grupos de plan de Gemini admiten parámetros distintos; lea "Diferencias entre los dos grupos" más abajo antes de integrar.

Primera solicitud

Todos los modelos de chat de Gemini usan el protocolo compatible con OpenAI Chat Completions. Autentíquese con Authorization: Bearer sk-tu-clave; también se acepta x-api-key.

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "Hola"}]
  }'

Los modelos de Gemini disponibles varían según el grupo del plan. Llame a GET /v1/models con la clave actual y use únicamente los ID completos que devuelva esa respuesta.

No se admiten x-goog-api-key ni /v1beta/models/{model}:generateContent. /v1/responses y /v1/messages solo funcionan en el grupo Gemini (todos los modelos, incl. imagen); Gemini oficial directo no los admite (vea «Diferencias entre los dos grupos» más abajo).

Modelos disponibles

Use gemini-3.8-flash de forma predeterminada. Trate todo ID de modelo que contenga preview como una vista previa sin garantía de estabilidad.

Las tarifas varían según el grupo del plan. El catálogo de modelos con la sesión iniciada para la clave actual es la fuente autorizada.

Diferencias entre los dos grupos

En Gemini oficial directo con formato OpenAI, tools, response_format, stop, n y campos similares no dan error pero se ignoran. Para llamadas a herramientas o salida estructurada, use el formato nativo (generationConfig.responseMimeType / responseSchema) o una clave del grupo Gemini (todos los modelos, incl. imagen).

La salida estructurada de Gemini (todos los modelos, incl. imagen) admite response_format con json_object y json_schema.

Parámetros habituales en Gemini oficial directo

• messages: de las partes de contenido solo se leen text e image_url, y image_url solo acepta data URL en base64.
• max_tokens / max_completion_tokens: si envía ambos, prevalece max_tokens; los tokens de razonamiento cuentan para este límite, así que use al menos 4096.
• temperature / top_p: se reenvían sin cambios dentro del rango oficial del modelo.
• reasoning_effort: se convierte en presupuesto de razonamiento; vea "Razonamiento" más abajo.

El tipo y el valor predeterminado de cada campo están en la columna de Gemini de la referencia de API Chat Completions.

Transmisión con SSE (agregue "stream": true)

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro-preview", "stream": true,
    "messages": [{"role": "user", "content": "Hola"}]}'

En el grupo Gemini oficial directo, la transmisión genera primero la respuesta completa y solo después la envía en fragmentos. El primer fragmento llega aproximadamente cuando estaría lista la respuesta completa, y el último siempre incluye usage.

El grupo Gemini (todos los modelos, incl. imagen) transmite token por token; agregue stream_options.include_usage cuando necesite el uso.

Una respuesta sin streaming incluye el cargo en usage: cost_usd es el importe en USD que se descuenta realmente de su saldo, cost es el mismo cargo en CNY y currency es la moneda de cost (siempre CNY), con los mismos valores en los encabezados de respuesta X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency. Las respuestas en streaming no llevan ninguno; consulte el cargo en Uso de la consola. Vea Cargos.

Razonamiento (Thinking)

Los modelos de Gemini razonan de forma predeterminada y ese razonamiento no se puede desactivar por completo. Los tokens de razonamiento cuentan contra su límite de salida. Si max_tokens es demasiado bajo puede producirse finish_reason=length con solo unos pocos caracteres visibles, así que use al menos 4096.

En el formato OpenAI, los tokens de razonamiento ya están incluidos en completion_tokens, y el grupo Gemini (todos los modelos, incl. imagen) además los reporta en completion_tokens_details.reasoning_tokens. En el formato nativo se reportan por separado en usageMetadata.thoughtsTokenCount.

En Gemini oficial directo, reasoning_effort se convierte en presupuesto de razonamiento:

En el grupo Gemini (todos los modelos, incl. imagen), none reduce notablemente el razonamiento.

Transferencia directa del payload nativo de Gemini

Los cuerpos de solicitud provenientes del SDK de Gemini pueden enviarse tal cual: el mismo endpoint del grupo Gemini oficial directo también acepta el campo nativo contents, y la respuesta se devuelve con la forma nativa.

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "contents": [{"role": "user", "parts": [{"text": "Hola"}]}]
  }'

El formato nativo solo acepta los campos oficiales de nivel superior:

contents, systemInstruction, generationConfig, safetySettings, tools,
toolConfig, cachedContent, labels, serviceTier, model

Cualquier otro campo —store, max_tokens, messages, etc.— devuelve 400 Unknown name …. El formato nativo no admite transmisión; no envíe "stream": true.

Generación de video con Gemini Omni (Interactions nativo)

gemini-omni-flash-preview acepta texto, imágenes y video, y puede generar video directamente. La conversión de texto a video solo necesita model e input; envíela a POST https://api.hop-base.com/v1beta/interactions para obtener la respuesta de video nativa completa.

El endpoint de Chat Completions sigue disponible para chat de texto, pero no debe usarse para recibir el payload de video completo. POST /v1/interactions se mantiene como alias de compatibilidad.

curl https://api.hop-base.com/v1beta/interactions \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "Genera un video de 3 segundos de una pelota roja rodando lentamente sobre un fondo blanco"
  }'

El video está en steps[].content[], y data contiene un MP4 codificado en base64. usage.output_tokens_by_modality desglosa los tokens de salida por modalidad a título informativo; esas cifras ya están incluidas en total_output_tokens.

{
  "status": "completed",
  "model": "gemini-omni-flash-preview",
  "steps": [{
    "type": "model_output",
    "content": [{
      "type": "video",
      "mime_type": "video/mp4",
      "data": "<base64-mp4>"
    }]
  }],
  "usage": {
    "total_input_tokens": 20,
    "total_output_tokens": 17819,
    "output_tokens_by_modality": [{"modality": "video", "tokens": 17376}]
  }
}

El contexto del modelo es de 1,048,576 tokens; las capacidades y disponibilidad de la vista previa pueden cambiar. Consulte Video de Gemini Omni para el contrato completo.

Próximos pasos

• Para generar imágenes con Gemini (Banana), consulte la API de imágenes
• Para el video de Gemini Omni, consulte Video de Gemini Omni
• Si algo falla, revise Solución de problemas