Gerar conteúdo

POST

v1beta

models

{model}

{operator}

import os
from google import genai

client = genai.Client(
    api_key=os.environ["COMETAPI_KEY"],
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
)

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Explain how AI works in a few words",
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "<string>",
        "parts": [
          {
            "text": "<string>",
            "functionCall": {
              "name": "<string>",
              "args": {}
            },
            "inlineData": {
              "mimeType": "<string>",
              "data": "<string>"
            },
            "thought": true
          }
        ]
      },
      "safetyRatings": [
        {
          "category": "<string>",
          "probability": "<string>",
          "blocked": true
        }
      ],
      "citationMetadata": {
        "citationSources": [
          {
            "startIndex": 123,
            "endIndex": 123,
            "uri": "<string>",
            "license": "<string>"
          }
        ]
      },
      "tokenCount": 123,
      "avgLogprobs": 123,
      "groundingMetadata": {
        "groundingChunks": [
          {
            "web": {
              "uri": "<string>",
              "title": "<string>"
            }
          }
        ],
        "groundingSupports": [
          {
            "groundingChunkIndices": [
              123
            ],
            "confidenceScores": [
              123
            ],
            "segment": {
              "startIndex": 123,
              "endIndex": 123,
              "text": "<string>"
            }
          }
        ],
        "webSearchQueries": [
          "<string>"
        ]
      },
      "index": 123
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "<string>",
        "probability": "<string>",
        "blocked": true
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 123,
    "candidatesTokenCount": 123,
    "totalTokenCount": 123,
    "trafficType": "<string>",
    "thoughtsTokenCount": 123,
    "promptTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ]
  },
  "modelVersion": "<string>",
  "createTime": "<string>",
  "responseId": "<string>"
}

A CometAPI oferece suporte ao formato de API nativa do Gemini, dando a você acesso completo a recursos específicos do Gemini, como controle de thinking, grounding com Google Search, modalidades nativas de geração de imagem e muito mais. Use este endpoint quando precisar de capacidades que não estão disponíveis por meio do endpoint de chat compatível com OpenAI.

Use a referência oficial da API GenerateContent do Google como fonte oficial para os campos completos da requisição, o schema da resposta e o comportamento específico dos modelos Gemini. Esta página da CometAPI explica como enviar esse formato de requisição nativo pela CometAPI.

Os parâmetros de solicitação e os campos de resposta do Gemini podem mudar à medida que o Google atualiza a API nativa. Consulte a documentação de geração de texto do Gemini para ver a lista completa mais recente de parâmetros e o comportamento específico do provedor.

Tanto os headers x-goog-api-key quanto Authorization: Bearer são compatíveis para autenticação.

Início rápido

Para usar qualquer SDK do Gemini ou cliente HTTP com a CometAPI, substitua a URL base e a chave de API:

Configuração	Padrão do Google	CometAPI
URL base	`generativelanguage.googleapis.com`	`api.cometapi.com`
Chave de API	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

Enviar entrada de vídeo

O generateContent do Gemini aceita vídeo como uma parte do conteúdo. Escolha o formato de entrada com base em onde o vídeo está armazenado:

Fonte do vídeo	Parte da solicitação	Usar quando
Arquivo de vídeo local	`inlineData`	O vídeo é pequeno o suficiente para ser enviado como base64 na solicitação JSON.
URL pública do vídeo	`fileData.fileUri`	O vídeo está disponível por meio de uma URL HTTPS pública que não exige autenticação.

Para solicitações REST e curl, use os nomes de campo em camelCase do Gemini, como inlineData.mimeType e fileData.fileUri. Não envie mídia por URL como file_data.file_uri.

Este exemplo lê um arquivo MP4 local, o codifica em base64 e o envia no corpo da solicitação:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_PATH="./your_video.mp4"
VIDEO_B64=$(base64 < "$VIDEO_PATH" | tr -d '\n')

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<EOF
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "video/mp4",
            "data": "${VIDEO_B64}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF

Este exemplo envia uma URL pública de MP4 com fileData.fileUri:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_URL="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<EOF
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "${VIDEO_URL}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF

A CometAPI não recomenda um fluxo separado de upload da API Gemini Files para este endpoint. Envie a mídia na própria solicitação generateContent com inlineData ou fileData.fileUri.

Configurar thinking (reasoning)

Os modelos Gemini podem realizar raciocínio interno antes de gerar uma resposta. O método de controle depende da geração do modelo.

Gemini 3 (thinkingLevel)
Gemini 2.5 (thinkingBudget)

Os modelos Gemini 3 usam thinkingLevel para controlar a profundidade do raciocínio. Níveis disponíveis: MINIMAL, LOW, MEDIUM, HIGH.Use gemini-3-flash-preview como model de exemplo padrão, a menos que você precise especificamente de uma variante diferente do Gemini 3.

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Explain quantum physics simply."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "LOW"}
    }
  }'

Os modelos Gemini 2.5 usam thinkingBudget para controle refinado no nível de Token:

0 — desativar o thinking
-1 — dinâmico (o modelo decide, padrão)
> 0 — orçamento específico de Tokens (por exemplo, 1024, 2048)

curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Solve this logic puzzle step by step."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingBudget": 2048}
    }
  }'

Usar thinkingLevel com modelos Gemini 2.5 (ou thinkingBudget com modelos Gemini 3) pode causar erros. Use o parâmetro correto para a versão do seu modelo.

Transmitir Responses

Para receber Server-Sent Events à medida que o modelo gera conteúdo, use streamGenerateContent?alt=sse como operador. Cada evento SSE contém uma linha data: com um objeto JSON GenerateContentResponse.

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --no-buffer \
  -d '{
    "contents": [{"parts": [{"text": "Write a short poem about the stars"}]}]
  }'

Definir instruções do sistema

Para orientar o comportamento do modelo ao longo de toda a conversa, use systemInstruction:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "What is 2+2?"}]}],
    "systemInstruction": {
      "parts": [{"text": "You are a math tutor. Always show your work."}]
    }
  }'

Solicitar saída JSON

Para forçar uma saída JSON estruturada, defina responseMimeType. Opcionalmente, forneça um responseSchema para validação rigorosa do schema:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "List 3 planets with their distances from the sun"}]}],
    "generationConfig": {
      "responseMimeType": "application/json"
    }
  }'

Ground com Google Search

Para ativar a pesquisa na web em tempo real, adicione uma ferramenta googleSearch:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Who won the euro 2024?"}]}],
    "tools": [{"google_search": {}}]
  }'

A resposta inclui groundingMetadata com URLs de origem e pontuações de confiança.

Exemplo de resposta

Uma resposta típica do endpoint Gemini da CometAPI:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Hello"}]
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.0023
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 1,
    "totalTokenCount": 30,
    "trafficType": "ON_DEMAND",
    "thoughtsTokenCount": 24,
    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 5}],
    "candidatesTokensDetails": [{"modality": "TEXT", "tokenCount": 1}]
  },
  "modelVersion": "gemini-3-flash-preview",
  "createTime": "2026-03-25T04:21:43.756483Z",
  "responseId": "CeynaY3LDtvG4_UP0qaCuQY"
}

O campo thoughtsTokenCount em usageMetadata mostra quantos Tokens o modelo gastou em raciocínio interno, mesmo quando a saída de pensamento não está incluída na resposta.

Compare com o endpoint compatível com OpenAI

Recurso	Gemini Native (`/v1beta/models/...`)	Compatível com OpenAI (`/v1/chat/completions`)
Controle de pensamento	`thinkingConfig` com `thinkingLevel` / `thinkingBudget`	Não disponível
Grounding do Google Search	`tools: [\{"google_search": \{\}\}]`	Não disponível
Grounding do Google Maps	`tools: [\{"googleMaps": \{\}\}]`	Não disponível
Modalidade de geração de imagem	`responseModalities: ["IMAGE"]`	Não disponível
Cabeçalho de autenticação	`x-goog-api-key` ou `Bearer`	Apenas `Bearer`
Formato de resposta	Gemini nativo (`candidates`, `parts`)	Formato OpenAI (`choices`, `message`)

Autorizações

x-goog-api-key

string

header

obrigatório

Your CometAPI key passed via the x-goog-api-key header. Bearer token authentication (Authorization: Bearer $COMETAPI_KEY) is also supported.

Parâmetros de caminho

model

string

obrigatório

Gemini model ID. Example: gemini-3-flash-preview, gemini-2.5-pro. See the Models page for current options.

operator

enum<string>

obrigatório

The operation to perform. Use generateContent for synchronous responses, or streamGenerateContent?alt=sse for Server-Sent Events streaming.

Opções disponíveis:

generateContent,

streamGenerateContent?alt=sse

Corpo

application/json

contents

object[]

Conversation content. Each entry has an optional role (user or model) and a parts array.

Show child attributes

systemInstruction

object

System instructions that guide the model's behavior across the entire conversation. Text only.

Show child attributes

tools

object[]

Tools the model may use to generate responses. Supports function declarations, Google Search, Google Maps, and code execution.

Show child attributes

toolConfig

object

Configuration for tool usage, such as function calling mode.

Show child attributes

safetySettings

object[]

Safety filter settings. Override default thresholds for specific harm categories.

Show child attributes

generationConfig

object

Configuration for model generation behavior including temperature, output length, and response format.

Show child attributes

cachedContent

string

The name of cached content to use as context. Format: cachedContents/{id}. See the Gemini context caching documentation for details.

Resposta

200 - application/json

Successful response. For streaming requests, the response is a stream of SSE events, each containing a GenerateContentResponse JSON object prefixed with data: .

candidates

object[]

The generated response candidates.

Show child attributes

promptFeedback

object

Feedback on the prompt, including safety blocking information.

Show child attributes

usageMetadata

object

Token usage statistics for the request.

Show child attributes

modelVersion

string

The model version that generated this response.

createTime

string

The timestamp when this response was created (ISO 8601 format).

responseId

string

Unique identifier for this response.

Criar uma Message

APIs de geração e edição de imagens

import os
from google import genai

client = genai.Client(
    api_key=os.environ["COMETAPI_KEY"],
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
)

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Explain how AI works in a few words",
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "<string>",
        "parts": [
          {
            "text": "<string>",
            "functionCall": {
              "name": "<string>",
              "args": {}
            },
            "inlineData": {
              "mimeType": "<string>",
              "data": "<string>"
            },
            "thought": true
          }
        ]
      },
      "safetyRatings": [
        {
          "category": "<string>",
          "probability": "<string>",
          "blocked": true
        }
      ],
      "citationMetadata": {
        "citationSources": [
          {
            "startIndex": 123,
            "endIndex": 123,
            "uri": "<string>",
            "license": "<string>"
          }
        ]
      },
      "tokenCount": 123,
      "avgLogprobs": 123,
      "groundingMetadata": {
        "groundingChunks": [
          {
            "web": {
              "uri": "<string>",
              "title": "<string>"
            }
          }
        ],
        "groundingSupports": [
          {
            "groundingChunkIndices": [
              123
            ],
            "confidenceScores": [
              123
            ],
            "segment": {
              "startIndex": 123,
              "endIndex": 123,
              "text": "<string>"
            }
          }
        ],
        "webSearchQueries": [
          "<string>"
        ]
      },
      "index": 123
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "<string>",
        "probability": "<string>",
        "blocked": true
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 123,
    "candidatesTokenCount": 123,
    "totalTokenCount": 123,
    "trafficType": "<string>",
    "thoughtsTokenCount": 123,
    "promptTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ]
  },
  "modelVersion": "<string>",
  "createTime": "<string>",
  "responseId": "<string>"
}

Moderação de conteúdo

Chaves de API

Início rápido

Enviar entrada de vídeo

Configurar thinking (reasoning)

Transmitir Responses

Definir instruções do sistema

Solicitar saída JSON

Ground com Google Search

Exemplo de resposta

Compare com o endpoint compatível com OpenAI

Autorizações

Parâmetros de caminho

Corpo

Resposta

​Início rápido

​Enviar entrada de vídeo

​Configurar thinking (reasoning)

​Transmitir Responses

​Definir instruções do sistema

​Solicitar saída JSON

​Ground com Google Search

​Exemplo de resposta

​Compare com o endpoint compatível com OpenAI

Autorizações

Parâmetros de caminho

Corpo

Resposta

Início rápido

Enviar entrada de vídeo

Configurar thinking (reasoning)

Transmitir Responses

Definir instruções do sistema

Solicitar saída JSON

Ground com Google Search

Exemplo de resposta

Compare com o endpoint compatível com OpenAI