Gemini nativo

Gerar Conteúdo

Gera conteúdo usando o formato da API Google Gemini

POST
/v1beta/models/{model}:generateContent

Use os formatos de requisição e resposta do Gemini com um modelo retornado por Listar Modelos. Nomes de campos em ProtoJSON lowerCamelCase e os correspondentes em proto snake_case são aceitos. Os campos e valores opcionais suportados dependem do modelo selecionado.

Parâmetros de Path

modelstringpathobrigatório

Nome do modelo (ex.: gemini-2.5-pro, gemini-3.5-flash).

Parâmetros de Query

keystringquery

Chave de API (alternativa à autenticação via cabeçalho).

Autenticação

Os endpoints do Gemini suportam múltiplos métodos de autenticação:

  • Parâmetro de query ?key=YOUR_API_KEY
  • Cabeçalho x-goog-api-key: YOUR_API_KEY
  • Cabeçalho Authorization: Bearer YOUR_API_KEY

Corpo da Requisição

contentsarrayobrigatório

Conteúdo da conversa com parts e uma role opcional. Partes de mídia usam inlineData / inline_data ou fileData / file_data. Arquivos e IDs de Cache criados pelo TokenLab só podem ser usados em seu respectivo Workspace.

systemInstructionobject

Instrução de sistema para o modelo.

generationConfigobject

Configurações de geração como temperature, topP, topK, maxOutputTokens, stopSequences, candidateCount, responseModalities, responseMimeType, responseSchema e thinkingConfig. Os nomes correspondentes em snake_case também são aceitos. Os valores e combinações suportados dependem do modelo.

safetySettingsarray

Configurações de filtros de segurança.

toolsarray

Ferramentas do Gemini como functionDeclarations. Os tipos de ferramentas suportados dependem do modelo.

toolConfigobject

Configuração de ferramentas como functionCallingConfig.

cachedContentstring

Nome do conteúdo em cache criado com Criar conteúdo em cache, por exemplo cachedContents/abc123. Funciona apenas no Workspace que o criou.

Todos os campos em lowerCamelCase mostrados acima também podem usar sua grafia oficial do proto em snake_case, por exemplo system_instruction, generation_config, safety_settings, tool_config, cached_content, file_data.file_uri e inline_data.mime_type.

Métodos Suportados

A API compatível com Gemini inclui Listar Modelos, Obter Modelo, generateContent, streamGenerateContent, countTokens, Files e conteúdo em cache. Gemini Interactions e Live não estão disponíveis.

Consulte a resposta de Obter Modelo do modelo antes de chamá-lo: supportedGenerationMethods lista as ações que o modelo aceita.

Resposta

candidatesarray

Candidatos de conteúdo gerados.

usageMetadataobject

Informações de uso de tokens.

Requisição

curl -X POST "https://api.tokenlab.sh/v1beta/models/gemini-2.5-pro:generateContent?key=sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [{"text": "Hello, Gemini!"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

Erros

  • 400 INVALID_ARGUMENT: o corpo da requisição não é válido, ou o modelo não aceita requisições do Gemini.
  • 401 UNAUTHENTICATED: a chave de API está ausente ou é inválida.
  • 402 RESOURCE_EXHAUSTED: o saldo é insuficiente para esta requisição.
  • 503 UNAVAILABLE: nenhuma rota está disponível para o modelo no momento. Tente novamente mais tarde.

Entrada de Mídia

Insira a mídia dentro de contents[].parts[] como bytes Base64 inline (inlineData ou inline_data) ou como uma URL https pública (fileData ou file_data). Imagens, áudios e vídeos são suportados.

Imagem

Use bytes de imagem inline:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Please describe this image." },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

Use a URL de uma imagem:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Please describe this image." },
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}

Áudio

Use a URL de um áudio, aqui com os nomes em snake_case do proto:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Transcribe and summarize this audio." },
        {
          "file_data": {
            "mime_type": "audio/mpeg",
            "file_uri": "https://example.com/sample.mp3"
          }
        }
      ]
    }
  ]
}

Vídeo

Use a URL de um vídeo:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Describe this video briefly." },
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://example.com/sample.mp4"
          }
        }
      ]
    }
  ]
}

Resposta

Response
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "Hello! How can I assist you today?"}
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE"}
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 10,
    "totalTokenCount": 15
  }
}

Contagem de tokens e embeddings

Contar Tokens (POST /v1beta/models/{model}:countTokens) precisa de uma chave de API e não é cobrado. Use a contagem para planejamento; a cobrança de uma requisição de geração vem do usageMetadata dessa resposta.

Modelos de embedding usam Criar Embedding (POST /v1/embeddings). Chame embedContent ou batchEmbedContents apenas para um modelo cuja resposta de Obter Modelo os liste em supportedGenerationMethods.

Autorização

AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Parâmetros de caminho

model*string

Nome do modelo (ex: gemini-2.5-pro)

Parâmetros de consulta

key?string

Chave de API (alternativa à autenticação via cabeçalho)

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

  • "auto"
  • "verified"
  • "official"

Corpo da requisição

application/json

Solicitação nativa Gemini GenerateContent. Nomes em lowerCamelCase do ProtoJSON e nomes originais em snake_case do proto são aceitos e preservados, incluindo solicitações mistas. Se ambas as grafias de um campo estiverem presentes, o TokenLab não as mescla nem escolhe uma precedência local. Campos desconhecidos são encaminhados com base no melhor esforço.

Resposta

application/json

application/json

application/json

application/json

application/json

application/json