Gemini Native Protocol API Reference

    Gemini Native Protocol API Reference

    Call Gemini models through the Gate.AI Gemini native protocol. Best for apps already using Gemini contents\[\], parts\[\], and tools\[\] request structures.

    FieldValue
    Base URLhttps://api.gate.ai/gemini/v1beta
    AuthAuthorization: Bearer <API_KEY>
    FormatGemini native JSON request body
    Text generationPOST /models/{model}:generateContent
    Streaming generationPOST /models/{model}:streamGenerateContent?alt=sse

    Gate.AI uses its own API Key. Do not use Google Gemini's ?key= query parameter.
    The Gemini native protocol selects the model via {model} in the URL path, for example POST /models/gemini-2.5-pro:generateContent. Do not pass model again in the request body. This differs from OpenAI Chat Completions, where model is sent in the request body.

    Equivalent Base URL paths

    ScenarioBase URL
    Gate.AI explicit Gemini protocol (recommended)https://api.gate.ai/gemini/v1beta
    Google AI Studio SDK direct access (without /gemini prefix)https://api.gate.ai/v1beta
    Vertex AI style path (with prefix)https://api.gate.ai/gemini/v1/publishers/google/models/{model}:{action}
    Vertex AI style path (without prefix)https://api.gate.ai/v1/publishers/google/models/{model}:{action}

    Text generation

    POST/models/{model}:generateContent

    Generate a model reply from a Gemini native contents request body.

    Request Parameters

    NameInTypeRequiredDescription
    AuthorizationheaderstringYesGate.AI API Key. Format: Bearer <API_KEY>
    Content-TypeheaderstringYesRequest body format: application/json
    modelpathstringYesGemini model ID, such as gemini-2.5-pro

    Request Body

    NameTypeRequiredDescription
    contentsarrayYesGemini conversation turns in order
    contents\[\].rolestringNouser or model
    contents\[\].partsarrayYesContent parts in one turn
    parts\[\].textstringNoText input
    parts\[\].inlineDataobjectNoMultimodal input with mimeType and base64 data
    toolsarrayNoTool declarations in Gemini functionDeclarations format
    toolConfigobjectNoTool calling policy
    generationConfigobjectNoGeneration settings such as temperature and maxOutputTokens
    systemInstructionobjectNoSystem instruction

    Example

    bash
    1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"23curl https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:generateContent \4  -H "Authorization: Bearer $GATEAI_API_KEY" \5  -H "Content-Type: application/json" \6  -d '{7    "contents": [8      {9        "role": "user",10        "parts": [11          {"text": "Introduce Gate.AI in one sentence"}12        ]13      }14    ]15  }'

    Response Fields

    NameTypeDescription
    candidatesarrayModel candidate replies
    candidates\[\].indexintegerCandidate index, starting at 0
    candidates\[\].content.rolestringAlways model
    candidates\[\].content.parts\[\].textstringText reply content
    candidates\[\].content.parts\[\].thoughtbooleanWhether the part is model reasoning content
    candidates\[\].content.parts\[\].thoughtSignaturestringThought signature for multi-turn reasoning context
    candidates\[\].content.parts\[\].functionCallobjectTool call request
    candidates\[\].finishReasonstringFinish reason, such as STOP
    usageMetadataobjectUsage and billing metadata
    usageMetadata.promptTokenCountintegerInput token count
    usageMetadata.candidatesTokenCountintegerOutput token count
    usageMetadata.totalTokenCountintegerTotal token count
    usageMetadata.coststringRequest cost in USD

    Response Example

    json
    1{2  "candidates": [3    {4      "index": 0,5      "content": {6        "role": "model",7        "parts": [8          {9            "text": "Gate.AI is a unified AI model routing platform."10          }11        ]12      },13      "finishReason": "STOP"14    }15  ],16  "usageMetadata": {17    "promptTokenCount": 13,18    "candidatesTokenCount": 37,19    "totalTokenCount": 50,20    "cost": "0.0000964"21  }22}

    Streaming generation

    POST/models/{model}:streamGenerateContent?alt=sse

    Stream Gemini response chunks. The final chunk usually includes usageMetadata. Read candidates\[\].content.parts\[\].text according to the Gemini streaming protocol.

    Request Parameters

    NameInTypeRequiredDescription
    AuthorizationheaderstringYesGate.AI API Key. Format: Bearer <API_KEY>
    Content-TypeheaderstringYesRequest body format: application/json
    modelpathstringYesGemini model ID, such as gemini-2.5-pro

    Request Body

    NameTypeRequiredDescription
    contentsarrayYesGemini conversation turns in order
    contents\[\].rolestringNouser or model
    contents\[\].partsarrayYesContent parts in one turn
    parts\[\].textstringNoText input
    parts\[\].inlineDataobjectNoMultimodal input with mimeType and base64 data
    toolsarrayNoTool declarations in Gemini functionDeclarations format
    toolConfigobjectNoTool calling policy
    generationConfigobjectNoGeneration settings such as temperature and maxOutputTokens
    systemInstructionobjectNoSystem instruction

    Example

    bash
    1curl -N "https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \2  -H "Authorization: Bearer $GATEAI_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "contents": [6      {7        "role": "user",8        "parts": [9          {"text": "List three scenarios where model routing is useful"}10        ]11      }12    ]13  }'

    Multimodal input

    Put images, audio, video, PDF, and other content in the same parts[]. Gate.AI Gemini entry recommends camelCase fields: inlineData.mimeType.

    TypemimeType examples
    Imageimage/png, image/jpeg
    Audioaudio/mp3, audio/wav
    Videovideo/mp4
    PDFapplication/pdf

    Image input example

    ini
    1IMAGE_B64="$(base64 -i ./image.png | tr -d '\n')"23curl https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:generateContent \4  -H "Authorization: Bearer $GATEAI_API_KEY" \5  -H "Content-Type: application/json" \6  -d "{7    \"contents\": [8      {9        \"role\": \"user\",10        \"parts\": [11          {\"text\": \"Describe this image\"},12          {13            \"inlineData\": {14              \"mimeType\": \"image/png\",15              \"data\": \"${IMAGE_B64}\"16            }17          }18        ]19      }20    ]21  }"

    Tool calling

    Gemini tools use tools[].functionDeclarations[]. Put the tool policy in toolConfig.functionCallingConfig.

    json
    1{2  "contents": [3    {4      "role": "user",5      "parts": [6        {"text": "What should I wear in Beijing today?"}7      ]8    }9  ],10  "tools": [11    {12      "functionDeclarations": [13        {14          "name": "get_weather",15          "description": "Query city weather",16          "parameters": {17            "type": "object",18            "properties": {19              "city": {20                "type": "string",21                "description": "City name"22              }23            },24            "required": ["city"]25          }26        }27      ]28    }29  ],30  "toolConfig": {31    "functionCallingConfig": {32      "mode": "AUTO"33    }34  }35}

    When the model triggers a tool, it returns functionCall in candidates[].content.parts[].

    Status codes

    StatusMeaningDescription
    200OKRequest succeeded
    400Bad RequestInvalid request body or JSON, or missing required contents / parts
    401UnauthorizedInvalid or missing API Key
    402Payment RequiredInsufficient balance
    404Not FoundInvalid API path, unknown model, or model does not support this protocol
    413Payload Too LargeMultimodal request body too large
    429Too Many RequestsToo many requests. Reduce call frequency.
    500Internal Server ErrorInternal server error
    502Bad GatewayUpstream Gemini service failed

    Difference from OpenAI-compatible access

    If your app already uses OpenAI Chat Completions, you can keep calling Gemini models via https://api.gate.ai/openai/v1/chat/completions. If your app already uses Gemini native contents\[\] / parts\[\] format, use the /gemini/v1beta/models/... endpoints on this page for lower migration cost.

    FAQ

    SymptomCauseSuggested fix
    404Missing /gemini/v1beta in the path or wrong model IDUse https://api.gate.ai/gemini/v1beta/models/{model}:generateContent
    Multimodal content not readWrong inlineData field names, MIME type, or base64Use inlineData.mimeType/data and ensure base64 has no line breaks
    Tool not triggeredSchema exceeds Gemini JSON Schema subsetStart with basic fields such as type, properties, required, and description