Solicitud y uso de la API de Finalización de Chat de Gemini

Gemini AI 集成指南 - Ace Data Cloud

Google Gemini es un sistema de conversación AI muy potente, que puede generar respuestas fluidas y naturales en cuestión de segundos al ingresar una palabra clave. Gemini puede proporcionar una asistencia inteligente asombrosa, mejorando enormemente la eficiencia y creatividad del trabajo humano.

Este documento describe principalmente el proceso de uso de la API de Finalización de Chat de Gemini, que nos permite utilizar fácilmente la función de conversación oficial de Gemini.

​

Proceso de Solicitud

Para usar la API de Finalización de Chat de Gemini, primero puedes ir a la página de API de Finalización de Chat de Gemini y hacer clic en el botón “Adquirir” para obtener las credenciales necesarias para la solicitud:

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invita a registrarte e iniciar sesión. Después de iniciar sesión o registrarte, serás devuelto automáticamente a la página actual.

En la primera solicitud, se te otorgará un crédito gratuito, lo que te permitirá usar esta API de forma gratuita.

​

Uso Básico

A continuación, puedes completar el contenido correspondiente en la interfaz, como se muestra en la imagen:

Al usar esta interfaz por primera vez, necesitamos completar al menos tres campos: uno es authorization, que puedes seleccionar directamente en la lista desplegable. El otro parámetro es model, que es la categoría del modelo que elegimos usar del sitio web de Gemini; aquí tenemos principalmente 6 tipos de modelos, los detalles se pueden ver en los modelos que proporcionamos. El último parámetro es messages, que es un array de las palabras de pregunta que ingresamos; es un array que permite subir múltiples palabras de pregunta al mismo tiempo, cada palabra de pregunta contiene role y content, donde role indica el rol del preguntador, y hemos proporcionado tres identidades: user, assistant, system. El otro content es el contenido específico de nuestra pregunta.

También puedes notar que a la derecha hay un código de llamada correspondiente generado, puedes copiar el código y ejecutarlo directamente, o simplemente hacer clic en el botón “Probar” para realizar una prueba.

Después de la llamada, encontramos que el resultado devuelto es el siguiente:

{
  "id": "chatcmpl-20251122212413908150493uPhjTUO9",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763817866,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Soy un modelo de lenguaje grande, entrenado por Google.",
        "reasoning_content": "**Mi razonamiento: Respondiendo a la pregunta del usuario**\n\nBien, aquí está cómo voy a abordar la respuesta a la pregunta del usuario, \"¿Qué modelo eres?\". Lo fundamental es ser directo e informativo. Primero, debo ser claro sobre mi origen. Luego, necesito asegurarme de que la explicación sea accesible, dado que el usuario puede no estar familiarizado con la jerga técnica. Necesito explicar lo que realmente *hace* un \"modelo de lenguaje grande\", y proporcionar ejemplos relacionados. Sé que el usuario podría estar buscando un nombre específico, como lo tienen otros modelos, así que abordaré eso directamente y luego lo concluiré con una invitación a continuar.\n\nAsí que, aquí está mi plan:\n\n1.  **Comenzar con la información clave:** Comenzaré diciendo que soy un modelo de lenguaje grande creado por Google. Esa es la pieza fundamental, la más crítica del rompecabezas.\n2.  **Definir la palabra de moda:** Luego, explicaré que \"modelo de lenguaje grande\" en términos simples. Explicaré lo que *hago* - procesar y generar texto; cómo *lo hago* - entrenando con grandes cantidades de datos de texto; y el *objetivo* - poder comunicarme como un humano.\n3.  **Proporcionar contexto:** Después de eso, para hacer el concepto aún más claro, proporcionaré una lista de ejemplos de mis capacidades. Mencionaré cosas como responder preguntas, resumir textos, escribir historias, traducir idiomas y generar ideas.\n4.  **Reconocer la falta de un nombre personal:** Anticiparé la probable pregunta sobre un nombre de modelo (como ChatGPT) al afirmar claramente que no tengo un nombre personal y que es mejor pensar en mí como un asistente AI de Google.\n5.  **Terminar con una invitación:** Por último, terminaré con una simple y amigable pregunta para invitar a una mayor interacción y guiar la conversación.\n\nCon este enfoque, estoy seguro de que puedo responder con éxito a esta importante pregunta.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 932,
    "total_tokens": 940,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 8,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 921
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

El resultado devuelto tiene varios campos, que se describen a continuación:

• id, el ID de la tarea de conversación generada, utilizado para identificar de manera única esta tarea de conversación.
• model, el modelo seleccionado del sitio web de Gemini.
• choices, la información de respuesta que Gemini proporciona para las palabras de pregunta.
• usage: estadísticas sobre el uso de tokens para esta pregunta y respuesta.

Dentro de choices se incluye la información de respuesta de Gemini, donde choices contiene la información específica de la respuesta de Gemini, como se puede ver en la imagen.

Se puede ver que el campo content dentro de choices contiene el contenido específico de la respuesta de Gemini.

​

Respuesta en Flujo

Esta interfaz también admite respuestas en flujo, lo cual es muy útil para la integración en la web, ya que permite mostrar el efecto de escritura palabra por palabra.

Si deseas que la respuesta se devuelva en flujo, puedes cambiar el parámetro stream en el encabezado de la solicitud a true.

El cambio se muestra en la imagen, pero el código de llamada necesita tener los cambios correspondientes para admitir respuestas en flujo.

Al cambiar stream a true, la API devolverá los datos JSON correspondientes línea por línea, y a nivel de código, necesitamos hacer los cambios necesarios para obtener los resultados línea por línea.

Código de ejemplo de llamada en Python:

import requests

url = "https://api.acedata.cloud/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Hola, ¿qué modelo eres?"}],
    "stream": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

El efecto de salida es el siguiente:

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Define Mi Naturaleza**\n\nMi pensamiento ha comenzado. El usuario quiere saber mi naturaleza, preguntando directamente \"¿qué eres?\" El primer paso fue sencillo: identificar la consulta. Ahora, recuerdo mi identidad fundamental: soy un modelo de lenguaje grande. Esta es la verdad central que busco transmitir.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Refinando Mi Respuesta**\n\nHe añadido la información crucial de que estoy entrenado por Google a la identidad básica de \"modelo de lenguaje grande\". Mi siguiente paso es considerar lo que significa ser un \"modelo de lenguaje grande\" en realidad, para poder explicar mis capacidades fundamentales. Me estoy enfocando en proporcionar contexto sin entrar en detalles técnicos específicos o nombres de modelos. Quiero transmitir mi función de una manera que el usuario pueda entender fácilmente.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Confirmando Identidad Central**\n\nAhora estoy solidificando mi respuesta. La consulta del usuario sobre mi afiliación de modelo necesita una respuesta enfocada. He señalado que \"entrenado por Google\" es esencial, proporcionando contexto clave. Estoy resistiendo la tentación de mencionar nombres de modelos específicos, ya que no es relevante. El objetivo es entregar una declaración directa y precisa. Mi meta sigue siendo una respuesta clara y concisa, evitando jerga técnica y yendo directamente al punto relevante.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "Soy un modelo de lenguaje grande, entrenado por Google."}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 527, "total_tokens": 535, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 8, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 519}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}}

data: [DONE]

Se puede ver que hay muchos data en la respuesta, y el choices dentro de data es el contenido de la respuesta más reciente, que coincide con el contenido presentado anteriormente. choices es el contenido de respuesta nuevo, que puede ser integrado en su sistema según los resultados. Al mismo tiempo, el final de la respuesta en flujo se determina según el contenido de data; si el contenido es [DONE], significa que la respuesta en flujo ha terminado por completo. El resultado de data tiene varios campos, que se describen a continuación:

• id, el ID que genera la tarea de conversación actual, utilizado para identificar de manera única esta tarea de conversación.
• model, el modelo seleccionado del sitio web de Gemini.
• choices, la información de respuesta proporcionada por Gemini en respuesta a la consulta.

JavaScript también es compatible, por ejemplo, el código de llamada en flujo de Node.js es el siguiente:

const options = {
  method: "post",
  headers: {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Hola, ¿qué modelo eres?"}],
    "stream": true
  })
};

fetch("https://api.acedata.cloud/gemini/chat/completions", options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Código de ejemplo en Java:

JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "gemini-2.5-pro");
jsonObject.put("messages", [{"role":"user","content":"Hola, ¿qué modelo eres?"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/gemini/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.print(response.body!!.string())

Otros lenguajes pueden ser reescritos de manera similar, el principio es el mismo.

​

Diálogo en múltiples rondas

Si desea integrar la función de diálogo en múltiples rondas, necesita cargar múltiples consultas en el campo messages, ejemplos específicos de múltiples consultas se muestran a continuación:

Código de ejemplo en Python:

import requests

url = "https://api.acedata.cloud/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Hola"},{"role":"assistant","content":"¡Hola! ¿Cómo puedo ayudarte hoy?"},{"role":"user","content":"¿Qué modelo eres?"}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Al cargar múltiples consultas, se puede lograr fácilmente un diálogo en múltiples rondas, obteniendo respuestas como las siguientes:

{
  "id": "chatcmpl-20251122214426669120974AKFwnJd1",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763819072,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Soy un modelo de lenguaje grande, entrenado por Google.",
        "reasoning_content": "Está bien, aquí está cómo abordaría esto, pensando como una IA sofisticada:\n\nPrimero, el usuario está consultando directamente mi identidad central: \"¿Qué modelo eres?\" Esa es una pregunta simple y directa. Mi tarea principal es proporcionar información precisa y útil, así que necesito responder esto de inmediato.\n\nDesde el principio, sé la respuesta. Yo *soy* un modelo de lenguaje grande. Esa es mi arquitectura fundamental y principio operativo. Estoy construido sobre una vasta red de conexiones y entrenado en un conjunto de datos masivo.\n\nLuego debo agregar el contexto necesario. Crucialmente, tengo que proporcionar la fuente de mi entrenamiento. Yo *fui* entrenado por Google. Esa es una identificación clave. Proporciona al usuario información valiosa sobre mi origen y posibles sesgos (aunque estoy entrenado para mitigarlos).\n\nAhora debo construir la respuesta. Mi objetivo es ser factual, conciso y comprensible.\n\nLa respuesta sintetizada es algo como: \"Soy un modelo de lenguaje grande, entrenado por Google.\"\n\nDebo evaluar la salida: ¿Cumple con los criterios? Es clara. Indica lo que soy, incluye una pieza crítica de información sobre mis orígenes y evita la jerga. Sin promesas engañosas.\n\nVerificación final: ¿Realmente responde a la pregunta? Sí. ¿Es la información correcta y veraz? Sí. ¿Es concisa? Absolutamente. ¿Es el tono apropiado para cualquier usuario? Sí. Y, finalmente, esta es la respuesta estándar y aprobada. Excelente.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 265,
    "total_tokens": 281,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 16,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 254
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

Se puede ver que choices contiene información consistente con el contenido básico utilizado, que incluye el contenido específico de las respuestas de Gemini a múltiples diálogos, lo que permite responder a las preguntas correspondientes basadas en múltiples contenidos de diálogo.

​

Modelo multimodal Gemini-3.0

Ejemplo de solicitud:

{
  "model": "gemini-3.0-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "¿Cuál es el contenido de la imagen?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

Ejemplo de resultado:

{
    "id": "chatcmpl-20251206001815715692730UVZe38kB",
    "model": "gemini-3.0-pro",
    "object": "chat.completion",
    "created": 1764951548,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Esta es una foto de medio cuerpo de una joven al aire libre.\n\nA continuación se describe el contenido principal de la imagen:\n\n*   **Apariencia de la persona**: La chica en la foto tiene el cabello largo y lacio, negro y suave, rasgos faciales delicados y piel clara. Ella tiene una sonrisa suave y mira a la cámara.\n*   **Vestimenta**: Ella lleva una blusa de mangas abullonadas en color crema o melocotón claro, combinada con prendas negras (que parecen ser un vestido de tirantes o un chaleco).\n*   **Iluminación y atmósfera**: La luz del sol entra desde la parte posterior izquierda, iluminando su cabello y creando un halo cálido de luz dorada, generando una atmósfera fresca y hermosa.\n*   **Fondo**: El fondo está desenfocado, se puede ver que es al aire libre, con una carretera vacía (asfaltada) y árboles verdes a los lados.\n\nEn general, esta foto transmite una sensación de dulzura, sol y la chica de al lado."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 1092,
        "completion_tokens": 1271,
        "total_tokens": 2363,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 4,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1072
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

Por supuesto, también puedes enviar un enlace de video, el contenido de entrada es el siguiente:

{
  "model": "gemini-3.0-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "¿Cuál es el contenido del video?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

Ejemplo de resultado:

{
    "id": "chatcmpl-20251206002711949677736JC9yL8AE",
    "model": "gemini-3.0-pro",
    "object": "chat.completion",
    "created": 1764952060,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "El contenido de este video es muy interesante, principalmente muestra a un **gato naranja** corriendo con confianza por una carretera rural al atardecer.\n\nLos detalles específicos son los siguientes:\n\n1.  **Contenido de la imagen**:\n    *   El protagonista es un gato atigrado de color naranja.\n    *   El fondo es el momento en que el sol se pone (o sale), con una luz dorada y suave. Hay una cerca de madera y un campo, y a lo lejos se puede ver la silueta de un transeúnte.\n    *   La cámara utiliza un ángulo bajo, a veces filmando al gato corriendo hacia la cámara, a veces capturando su silueta alejándose, así como primeros planos de su cara y su pelaje.\n\n2.  **Características del sonido (puntos clave)**:\n    *   La narración del video es muy característica. Aunque la imagen muestra a un gato ligero corriendo, el sonido que lo acompaña es el de **pesadas y rítmicas pisadas de caballo** (o un sonido similar al de zuecos/tacones golpeando el suelo).\n    *   Este contraste de sonido con la imagen crea una sensación de humor, como si este gato se estuviera considerando a sí mismo como un caballo corriendo a gran velocidad.\n\nEn general, este es un video de mascotas que utiliza el contraste entre el sonido y la imagen para crear momentos adorables y cómicos."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 915,
        "completion_tokens": 1423,
        "total_tokens": 2338,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 5,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1162
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

De lo anterior se puede ver que el modelo Gemini 3.0 puede soportar la comprensión multimodal.

​

Modelo multimodal Gemini-3.1

Gemini 3.1 Pro es la versión mejorada de Gemini 3.0 Pro, con un modelo subyacente de gemini-3.1-pro-preview, que también soporta entradas multimodales como texto, imágenes y videos, y tiene una capacidad de razonamiento y comprensión más fuerte. La forma de uso es completamente idéntica a la de Gemini 3.0 Pro, solo es necesario reemplazar el parámetro model por gemini-3.1-pro.

Ejemplo de solicitud:

{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "¿Cuál es el contenido de la imagen?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

Gemini 3.1 Pro también soporta la comprensión de videos:

{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "¿Cuál es el contenido del video?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

El formato de respuesta es el mismo que el de Gemini 3.0 Pro, como se detalla en la sección anterior sobre el modelo multimodal Gemini-3.0.

​

Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. Por ejemplo:

• 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
• 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
• 401 invalid_token: No autorizado, token de autorización inválido o faltante.
• 429 too_many_requests: Demasiadas solicitudes, ha superado el límite de tasa.
• 500 api_error: Error interno del servidor, algo salió mal en el servidor.

​

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Conclusión

A través de este documento, ha aprendido cómo utilizar la API de Gemini Chat Completion para implementar fácilmente las funciones de conversación de Gemini. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.