Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt

Use this file to discover all available pages before exploring further.

Encaminhamento para Modelos Gemini

Para a série Gemini, fornecemos dois métodos de invocação: chamadas nativas da API e chamadas compatíveis com OpenAI.
Antes de começar, certifique-se de instalar ou atualizar a dependência nativa executando pip install google-genai ou pip install -U google-genai.
1️⃣ Para integração nativa, o Gemini cuida automaticamente do roteamento de tráfego entre AI Studio e VertexAI. Basta fornecer sua chave de API AIHubMix e a URL de requisição apropriada. Lembre-se de que esta URL é diferente da base_url usual — siga o exemplo abaixo para garantir a configuração correta.
client = genai.Client(
    api_key="sk-***",  # Replace with the key you generated from AiHubMix
    http_options={"base_url": "https://aihubmix.com/gemini"},
)
2️⃣ Para formatos compatíveis com OpenAI, mantenha o endpoint universal v1.
client = OpenAI(
    api_key="sk-***", # Replace with the key you generated from AiHubMix
    base_url="https://aihubmix.com/v1",
)
3️⃣ Para a série 2.5, se você precisa exibir o processo de raciocínio, existem duas maneiras de fazer isso:
  1. Invocação nativa: Passe include_thoughts=True
  2. Método compatível com OpenAI: Passe reasoning_effort
Você pode consultar os exemplos de código abaixo para uso detalhado.

Instruções do Gemini 3 Pro Image Preview

O Gemini 3 Pro Image Preview (Nano Banana Pro Preview) foi projetado para criação profissional de ativos e instruções complexas. Este modelo oferece os seguintes recursos:
  • Usa o Google Search para recuperar conhecimento mundial em tempo real
  • Processo “thinking” integrado (otimiza a composição antes da geração)
  • Pode gerar imagens com resoluções de até 4K
Modo Streaming (stream=True) → apenas estágio de raciocínio
Modo Não-Streaming (stream=False) → geração final da imagem
As imagens geradas não são incluídas nas respostas em streaming e devem ser recuperadas usando uma requisição sem streaming .
Exemplos de uso em Python:
import os
from google import genai
from google.genai import types

API_KEY = "<YOUR AIHUBMIX API KEY>"  

client = genai.Client(
    api_key=API_KEY,
    http_options={"base_url": "https://aihubmix.com/gemini"},  
)

prompt = (
    "Da Vinci style anatomical sketch of a dissected Monarch butterfly. "
    "Detailed drawings of the head, wings, and legs on textured parchment with notes in English."
)

# Optional parameters
aspect_ratio = "1:1"   # Supported: "1:1","2:3","3:2","3:4","4:3","4:5","5:4","9:16","16:9","21:9"
resolution   = "4K"    # Default: 1K. Supported: "1K", "2K", "4K". Note: “K” must be uppercase.

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=prompt,   
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
        image_config=types.ImageConfig(
            aspect_ratio=aspect_ratio,
            image_size=resolution,
        ),
    ),
)

# Save image & print text
for part in response.parts:
    if part.text:
        print(part.text)  
    elif image := part.as_image():
        image.save("butterfly.png")
        print("Image saved: butterfly.png")

Sobre os Modelos de Inferência Gemini 2.5

  1. A série 2.5 inteira consiste em modelos de inferência.
  2. 2.5 Flash é um modelo híbrido, similar ao Claude Sonnet 3.7. Você pode ajustar fino seu comportamento de raciocínio ajustando o parâmetro thinking_budget para controle ideal.
  3. 2.5 Pro é um modelo de inferência puro. O thinking não pode ser desabilitado, e thinking_budget não deve ser definido explicitamente.
Exemplos de uso em Python:
from google import genai
from google.genai import types

def generate():
    client = genai.Client(
        api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
        http_options={"base_url": "https://aihubmix.com/gemini"},
    )

    model = "gemini-2.0-flash"
    contents = [
        types.Content(
            role="user",
            parts=[
                types.Part.from_text(text="""How do I know I'm not wasting time?"""),
            ],
        ),
    ]

    print(client.models.generate_content(
        model=model,
        contents=contents,
    ))

if __name__ == "__main__":
    generate()

Gemini 2.5 Flash: Suporte a Tarefas Rápidas

Exemplo para invocação compatível com OpenAI:
from openai import OpenAI

client = OpenAI(
    api_key="AIHUBMIX_API_KEY", # Replace with the key you generated in AiHubMix
    base_url="https://aihubmix.com/v1",
)

completion = client.chat.completions.create(
    model="gemini-2.5-flash-preview-04-17-nothink",
    messages=[
        {
            "role": "user",
            "content": "Explain the Occam's Razor concept and provide everyday examples of it"
        }
    ]
)

print(completion.choices[0].message.content)
  1. Para tarefas complexas, basta definir o id do modelo como o padrão gemini-2.5-flash-preview-04-17 para habilitar o thinking.
  2. O Gemini 2.5 Flash usa o parâmetro budget para controlar a profundidade do thinking, variando de 0 a 16K. O budget padrão é 1024, e o efeito marginal ideal é 16K.

Compreensão de Mídia

  • Para arquivos multimídia com menos de 20MB (imagens, áudio, vídeo), envie-os usando inline_data.
  • Quando um arquivo multimídia for maior que 20MB, você deve usar a Files API.

Arquivos Abaixo de 20MB

Adicionando o parâmetro EDIARESOLUTION_MEDIUM, você pode ajustar a resolução da imagem, o que reduz significativamente os custos de entrada e minimiza o risco de erros com imagens grandes.Valores de resolução de mídia suportados:
NomeDescrição
MEDIA_RESOLUTION_UNSPECIFIEDA resolução de mídia não foi definida.
MEDIA_RESOLUTION_LOWResolução de mídia definida como baixa (64 tokens).
MEDIA_RESOLUTION_MEDIUMResolução de mídia definida como média (256 tokens).
MEDIA_RESOLUTION_HIGHResolução de mídia definida como alta (reenquadramento com zoom com 256 tokens).
Exemplos de uso em Python:
from google import genai
from google.genai import types

file_path = "yourpath/file.jpeg"
with open(file_path, "rb") as f:
    file_bytes = f.read()

client = genai.Client(
    api_key="sk-***", # Replace with the key you generated in AiHubMix
    http_options={"base_url": "https://aihubmix.com/gemini"}
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=file_bytes,
                    mime_type="image/jpeg"
                )
            ),
            types.Part(
                text="Describe the image."
            )
        ]
    ),
    config=types.GenerateContentConfig(
        system_instruction="You are a helpful assistant that can describe images.",
        max_output_tokens=768,
        temperature=0.1,
        thinking_config=types.ThinkingConfig(
            thinking_budget=0, include_thoughts=False
        ),
        media_resolution=types.MediaResolution.MEDIA_RESOLUTION_MEDIUM # 256 tokens
    )
)

print(response.text)

Files API

O Gemini pode lidar com vários tipos de dados de entrada simultaneamente, incluindo texto, imagens e áudio. Quando o tamanho total da requisição (incluindo arquivos, dicas de texto, comandos de sistema, etc.) excede 20 MB, certifique-se de usar a Files API.
  • Listar arquivos enviados não é suportado.
  • Os arquivos serão automaticamente excluídos após 48 horas, ou você pode excluir manualmente os arquivos enviados.
Exemplos de uso em Python:
from google import genai

client = genai.Client(
    api_key="sk-****",   
    http_options={"base_url": "https://aihubmix.com/gemini"},
)

myfile = client.files.upload(file="path/to/sample.mp3")

response = client.models.generate_content(
    model="gemini-2.5-flash", contents=["Describe this audio clip", myfile]
)

print(response.text)

Execução de Código

O recurso de execução de código permite que o modelo gere e execute código Python e aprenda iterativamente com os resultados até chegar a uma saída final. Você pode usar essa capacidade de execução de código para construir aplicações que se beneficiam de raciocínio baseado em código e produzem saída de texto. Por exemplo, você poderia usar a execução de código em uma aplicação que resolve equações ou processa texto.
Python
from google import genai
from google.genai import types

file_path = "yourpath/file.csv"
with open(file_path, "rb") as f:
    file_bytes = f.read()

client = genai.Client(
    api_key="sk-***", # Replace with the key you generated in AiHubMix
    http_options={"base_url": "https://aihubmix.com/gemini"}
)

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=file_bytes,
                    mime_type="text/csv"
                )
            ),
            types.Part(
                text="Please analyze this CSV and summarize the key statistics. Use code execution if needed."
            )
        ]
    ),
    config=types.GenerateContentConfig(
        tools=[types.Tool(
            code_execution=types.ToolCodeExecution
        )]
    )
)

for part in response.candidates[0].content.parts:
    if part.text is not None:
        print(part.text)
    if getattr(part, "executable_code", None) is not None:
        print("Generated code:\n", part.executable_code.code)
    if getattr(part, "code_execution_result", None) is not None:
        print("Execution result:\n", part.code_execution_result.output)

Cache de Contexto

A API nativa do Gemini habilita o cache de contexto implícito por padrão — sem necessidade de configuração. Para cada requisição generate_content, o sistema cacheia automaticamente o conteúdo de entrada. Se uma requisição subsequente usar exatamente o mesmo conteúdo, modelo e parâmetros, o sistema retornará instantaneamente o resultado anterior, acelerando drasticamente o tempo de resposta e potencialmente reduzindo os custos de tokens de entrada.
  • O cache é automático — sem necessidade de configuração manual.
  • O cache só é acertado quando o conteúdo, modelo e todos os parâmetros são exatamente os mesmos; qualquer diferença resultará em cache miss.
  • O time-to-live (TTL) do cache pode ser definido pelo desenvolvedor, ou deixado sem definição (padrão: 1 hora). Não há TTL mínimo ou máximo imposto pelo Google. Os custos dependem do número de tokens cacheados e da duração do cache.
    • Embora o Google não imponha restrição ao TTL, como uma plataforma de encaminhamento, suportamos apenas uma faixa limitada de TTL. Para requisitos além dos limites da nossa plataforma, entre em contato conosco.

Observações

  • Sem garantia de economia de custos: Tokens de cache são cobrados a 25% do preço padrão de entrada — então teoricamente, o cache pode economizar até 75% dos custos de tokens de entrada. No entanto, a documentação oficial do Google não garante economia de custos; o efeito real depende da sua taxa de acerto de cache, tipos de tokens e duração do armazenamento.
  • Condições de acerto de cache: Para maximizar a eficácia do cache, coloque o contexto repetível no início da entrada e o conteúdo dinâmico (como entrada do usuário) no final.
  • Como detectar acertos de cache: Se uma resposta vier do cache, response.usage_metadata incluirá o campo cache_tokens_details e cached_content_token_count. Você pode usá-los para determinar o uso do cache.
    Exemplo de campos quando um acerto de cache ocorre:
    cache_tokens_details=[ModalityTokenCount(modality=<MediaModality.TEXT: 'TEXT'>, token_count=2003)]
    cached_content_token_count=2003
    
Exemplo de código:
from google import genai

client = genai.Client(
    http_options={"base_url": "https://aihubmix.com/gemini"},
    api_key="sk-***",  # Replace with your AiHubMix API key
)

prompt = """
        <the entire contents of 'Pride and Prejudice'>
"""

def generate_content_sync():
    response = client.models.generate_content(
        model="gemini-2.5-flash-preview-05-20",
        contents=prompt + "Analyze the major themes in 'Pride and Prejudice'.",
    )
    print(response.usage_metadata)  # When cache is hit, cache_tokens_details and cached_content_token_count will appear
    return response

generate_content_sync()
Quando ocorre um acerto de cache, response.usage_metadata conterá:
cache_tokens_details=[ModalityTokenCount(modality=<MediaModality.TEXT: 'TEXT'>, token_count=2003)]
cached_content_token_count=2003
Conclusão principal: O cache implícito é automático e fornece feedback claro de acerto de cache. Os desenvolvedores podem verificar usage_metadata para o status do cache. A economia de custos não é garantida — o benefício real depende da estrutura da requisição e das taxas de acerto de cache.

Function calling

Ao usar a forma compatível com OpenAI para chamar a function calling do Gemini, você precisa passar tool_choice="auto" no corpo da requisição, caso contrário ele relatará um erro.
from openai import OpenAI

# Define the function declaration for the model
schedule_meeting_function = {
    "name": "schedule_meeting",
    "description": "Schedules a meeting with specified attendees at a given time and date.",
    "parameters": {
        "type": "object",
        "properties": {
            "attendees": {
                "type": "array",
                "items": {"type": "string"},
                "description": "List of people attending the meeting.",
            },
            "date": {
                "type": "string",
                "description": "Date of the meeting (e.g., '2024-07-29')",
            },
            "time": {
                "type": "string",
                "description": "Time of the meeting (e.g., '15:00')",
            },
            "topic": {
                "type": "string",
                "description": "The subject or topic of the meeting.",
            },
        },
        "required": ["attendees", "date", "time", "topic"],
    },
}

# Configure the client
client = OpenAI(
    api_key="AIHUBMIX_API_KEY", # Replace with the key you generated in AiHubMix
    base_url="https://aihubmix.com/v1",
)

# Send request with function declarations using OpenAI compatible format
response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[
        {"role": "user", "content": "Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about the Q3 planning."}
    ],
    tools=[{"type": "function", "function": schedule_meeting_function}],
    tool_choice="auto" ## 📍 Added Aihubmix compatibility, more stable request method
)

# Check for a function call
if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    function_call = tool_call.function
    print(f"Function to call: {function_call.name}")
    print(f"Arguments: {function_call.arguments}")
    print(response.usage)
    #  In a real app, you would call your function here:
    #  result = schedule_meeting(**json.loads(function_call.arguments))
else:
    print("No function call found in the response.")
    print(response.choices[0].message.content)
Exemplo de Saída:
Function to call: schedule_meeting
Arguments: {"attendees":["Bob","Alice"],"date":"2025-03-14","time":"10:00","topic":"Q3 planning"}
CompletionUsage(completion_tokens=28, prompt_tokens=111, total_tokens=139, completion_tokens_details=None, prompt_tokens_details=None)

Rastreamento Simplificado de Uso de Tokens

  1. O Gemini rastreia o uso de tokens usando usage_metadata. Veja o que cada campo significa:
    • prompt_token_count: número de tokens de entrada
    • candidates_token_count: número de tokens de saída
    • thoughts_token_count: tokens usados durante o raciocínio (também contados como saída)
    • total_token_count: total de tokens usados (entrada + saída)
    Para mais detalhes, consulte a documentação oficial.
  2. Para APIs usando o formato compatível com OpenAI, o uso de tokens é rastreado em .usage com os seguintes campos:
    • usage.completion_tokens: número de tokens de entrada
    • usage.prompt_tokens: número de tokens de saída (incluindo raciocínio)
    • usage.total_tokens: uso total de tokens

Veja como usá-lo no código:
from google import genai
from google.genai import types
import time

def generate():
    client = genai.Client(
        api_key="sk-***", # Replace this with your key from AiHubMix
        http_options={"base_url": "https://aihubmix.com/gemini"},
    )

    model = "gemini-2.5-pro-preview-03-25"
    contents = [
        types.Content(
            role="user",
            parts=[
                types.Part.from_text(text="""How is the "Rule of 72" derived in the financial world?"""),
            ],
        ),
    ]
    generate_content_config = types.GenerateContentConfig(
        response_mime_type="text/plain",
    )

    final_usage_metadata = None
    
    for chunk in client.models.generate_content_stream(
        model=model,
        contents=contents,
        config=generate_content_config,
    ):
        print(chunk.text, end="")
        if chunk.usage_metadata:
            final_usage_metadata = chunk.usage_metadata
    
    # Once all chunks are processed, print the full token usage
    if final_usage_metadata:
        print(f"\nUsage: {final_usage_metadata}")

if __name__ == "__main__":
    generate()

Última atualização: 2026-06-01