Skip to content
ajan.io

Docs menu

On this page

Google Completion API

Generate text with Google Gemini models through ajan's public API. Supports normal and streaming completions and is fully compatible with the official Vertex AI SDKs (Python / Node).

Google Completion Endpoint (v1beta)

Before You Start

  • API key: To use the API, create a personal API key or ask your workspace admin for a workspace API key with the Completion API scope.

Base URL

https://api.ajan.io/google/{region}/v1beta/models/{model}:generateContent

How It Works

This endpoint exposes Google Gemini models that are hosted in Google Vertex AI.\ It mirrors the structure of the official Vertex generateContent API. To use it, you need to:

Get available models

Call GET /{region}/v1beta/models/ to retrieve the list of Gemini models.

Pick a model & action

Choose a model ID and decide between generateContent or streamGenerateContent.

Send your request

POST to /{region}/v1beta/models/{model}:{action} with your prompt in contents.

Handle the response

Parse the JSON response for normal calls or consume the SSE events for streaming.

• Region selection (eu or us)\ • Optional Server-Sent Event (SSE) streaming with the same event labels used by the Google Python SDK (message_start, message_delta, message_stop)\ • A models discovery endpoint

Authentication

Send one of the following headers while using the ajan API Key:

Bearer \

Alternative header for the same API key.

Convenience header used by the official google-generative-ai Python SDK.

All headers are treated identically. Missing or invalid keys return 401 Unauthorized.

Authorization header example:

bash
curl -H "Authorization: Bearer $LD_API_KEY" \
     https://api.ajan.io/google/eu/v1beta/models

x-api-key header example:

bash
curl -H "x-api-key: $LD_API_KEY" \
     https://api.ajan.io/google/eu/v1beta/models

x-goog-api-key header example:

bash
curl -H "x-goog-api-key: $LD_API_KEY" \
     https://api.ajan.io/google/eu/v1beta/models

1. List available models

GET /{region}/v1beta/models

region must be eu or us.

Successful response

List of objects with the following shape:

  • name – Fully-qualified model name (e.g. models/gemini-2.5-flash).
  • supportedGenerationMethods – Always ["generateContent", "streamGenerateContent"].
bash
curl -H "Authorization: Bearer $LD_API_KEY" \
     https://api.ajan.io/google/eu/v1beta/models

2. Generate content

POST /{region}/v1beta/models/{model}:{action}

• model – The model ID as returned by the models endpoint (without the models/ prefix).\ • action – generateContent or streamGenerateContent depending on whether you want to use streaming or not.

Example path: google/eu/v1beta/models/gemini-2.5-flash:streamGenerateContent

Request body

The request body follows the official GenerateContentRequest structure.

Required fields

contents (Content\[], required)\ Conversation history. Each object has a role (string) and parts array containing objects with text (string).

json
"contents": [
  {
    "role": "user", 
    "parts": [
      {
        "text": "What's the weather like?"
      }
    ]
  }
]

Parts can also be functionCall and functionResponse objects for function calling. When you use a Gemini 3 model, return the thoughtSignature (and function-call id) from the model's functionCall part unchanged in your next request. The official SDKs do this for you; if you build requests by hand, copy the fields as-is.

model (string, required)\ The model to use for generation (e.g., "gemini-2.5-pro", "gemini-2.5-flash").

Optional fields

generationConfig (object, optional)\ Configuration for text generation. Supported fields:

  • temperature (number): Controls randomness (0.0-2.0)
  • topP (number): Nucleus sampling parameter (0.0-1.0)
  • topK (number): Top-k sampling parameter
  • candidateCount (number): Number of response candidates to generate
  • maxOutputTokens (number): Maximum number of tokens to generate
  • stopSequences (string\[]): Sequences that will stop generation
  • responseMimeType (string): MIME type of the response
  • responseSchema (object): Schema for structured output
json
"generationConfig": {
  "temperature": 0.7,
  "topP": 0.9,
  "topK": 40,
  "maxOutputTokens": 1000,
  "stopSequences": ["END", "STOP"]
}

safetySettings (SafetySetting\[], optional)\ Array of safety setting objects. Each object contains:

  • category (string): The harm category (e.g., "HARM\_CATEGORY\_HARASSMENT")
  • threshold (string): The blocking threshold (e.g., "BLOCK\_MEDIUM\_AND\_ABOVE")
json
"safetySettings": [
  {
    "category": "HARM_CATEGORY_HARASSMENT",
    "threshold": "BLOCK_MEDIUM_AND_ABOVE"
  }
]

tools (Tool\[], optional)\ Array of tool objects for function calling. Each tool contains functionDeclarations array with:

  • name (string): Function name
  • description (string): Function description
  • parameters (object): JSON schema defining function parameters
json
"tools": [
  {
    "functionDeclarations": [
      {
        "name": "get_weather",
        "description": "Get current weather information",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name"
            }
          }
        }
      }
    ]
  }
]

toolConfig (object, optional)\ Configuration for function calling. Contains functionCallingConfig with:

  • mode (string): Function calling mode ("ANY", "AUTO", "NONE")
  • allowedFunctionNames (string\[]): Array of allowed function names
json
"toolConfig": {
  "functionCallingConfig": {
    "mode": "ANY",
    "allowedFunctionNames": ["get_weather"]
  }
}

systemInstruction (string | Content, optional)\ System instruction to guide the model's behavior. Can be a string or Content object with role and parts.

json
"systemInstruction": {
  "role": "system",
  "parts": [
    {
      "text": "You are a weather agent. Use the weather tool when asked about weather."
    }
  ]
}

Minimal example

bash
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $LD_API_KEY" \
     https://api.ajan.io/google/us/v1beta/models/gemini-2.5-pro:generateContent \
     -d '{
       "contents": [{
         "role": "user",
         "parts": [{"text": "Write a short poem about the ocean."}]
       }]
     }'

Streaming

When action is streamGenerateContent the endpoint returns an text/event-stream with compatible events:

• message_start – first chunk that contains content\ • message_delta – subsequent chunks\ • message_stop – last chunk (contains finishReason and usage metadata)

Example message_delta event:

event: message_delta
data: {
  "candidates": [
    {
      "index": 0,
      "content": {
        "role": "model",
        "parts": [{ "text": "The ocean whispers..." }]
      }
    }
  ]
}

Python SDK example with function calling:

python
import google.generativeai as genai

def get_current_weather(location):
    """Get the current weather in a given location"""
    return f"The current weather in {location} is sunny with a temperature of 70 degrees and a wind speed of 5 mph."

genai.configure(
    api_key="<YOUR_AJAN_API_KEY>",

    transport="rest",  
    client_options={"api_endpoint": "https://api.ajan.io/google/<REGION>/"},
)

model = genai.GenerativeModel("gemini-2.5-flash", tools=[get_current_weather])

response = model.generate_content(
    "Please tell me the weather in San Francisco, then tell me a story on the history of the city"
)

print(response)

Python SDK streaming example:

python
model = genai.GenerativeModel("gemini-2.5-flash")

response = model.generate_content(
    "Tell me an elaborate story on the history of the city of San Francisco",
    stream=True,
)

for chunk in response:
    if chunk.text:
        print(chunk.text)

Using Google-compatible libraries

The endpoint is fully compatible with official Google SDKs including the Vertex AI Node SDK (@google-cloud/vertexai), Google Generative AI Python library (google-generative-ai), and the Vercel AI SDK for edge streaming.

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /google/{region}/v1beta/models/{model}:generateContent:
    post:
      tags:
        - Google
      summary: Generate Content
      description: >-
        Generate content using Google Gemini models.

        This endpoint mirrors the structure of the official Vertex AI
        generateContent API while adding API-key based authentication and region
        selection.
      operationId: google_generate_content_post
      parameters:
        - name: region
          in: path
          required: true
          description: The region of the API to use.
          schema:
            type: string
            enum:
              - eu
              - us
        - name: model
          in: path
          required: true
          description: The model ID (e.g., gemini-2.5-pro, gemini-2.5-flash).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contents:
                  type: array
                  description: >-
                    Conversation history. Parts may be text, functionCall, or
                    functionResponse.
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - model
                      parts:
                        type: array
                        items:
                          type: object
                          properties:
                            text:
                              type: string
                            thoughtSignature:
                              type: string
                              description: >-
                                Return unchanged on the follow-up turn (required
                                for Gemini 3).
                            functionCall:
                              type: object
                              properties:
                                name:
                                  type: string
                                args:
                                  type: object
                                id:
                                  type: string
                                  description: >-
                                    Return unchanged on the follow-up turn
                                    (required for Gemini 3).
                            functionResponse:
                              type: object
                              properties:
                                name:
                                  type: string
                                response:
                                  type: object
                                id:
                                  type: string
                                  description: >-
                                    Return unchanged on the follow-up turn
                                    (required for Gemini 3).
              required:
                - contents
            example:
              contents:
                - role: user
                  parts:
                    - text: Write a short haiku about the ocean.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  candidates:
                    type: array
                    items:
                      type: object
                      properties:
                        content:
                          type: object
                        finishReason:
                          type: string
                  usageMetadata:
                    type: object
        4XX:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ErrorResponse:
      properties:
        type:
          default: error
          enum:
            - error
          title: Type
          type: string
        error:
          discriminator:
            mapping:
              api_error:
                $ref: '#/components/schemas/APIError'
              authentication_error:
                $ref: '#/components/schemas/AuthenticationError'
              invalid_request_error:
                $ref: '#/components/schemas/InvalidRequestError'
              not_found_error:
                $ref: '#/components/schemas/NotFoundError'
              overloaded_error:
                $ref: '#/components/schemas/OverloadedError'
              permission_error:
                $ref: '#/components/schemas/PermissionError'
              rate_limit_error:
                $ref: '#/components/schemas/RateLimitError'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/InvalidRequestError'
            - $ref: '#/components/schemas/AuthenticationError'
            - $ref: '#/components/schemas/PermissionError'
            - $ref: '#/components/schemas/NotFoundError'
            - $ref: '#/components/schemas/RateLimitError'
            - $ref: '#/components/schemas/APIError'
            - $ref: '#/components/schemas/OverloadedError'
          title: Error
      required:
        - type
        - error
      title: ErrorResponse
      type: object
    APIError:
      properties:
        type:
          default: api_error
          enum:
            - api_error
          title: Type
          type: string
        message:
          default: Internal server error
          title: Message
          type: string
      required:
        - type
        - message
      title: APIError
      type: object
    AuthenticationError:
      properties:
        type:
          default: authentication_error
          enum:
            - authentication_error
          title: Type
          type: string
        message:
          default: Authentication error
          title: Message
          type: string
      required:
        - type
        - message
      title: AuthenticationError
      type: object
    InvalidRequestError:
      properties:
        type:
          default: invalid_request_error
          enum:
            - invalid_request_error
          title: Type
          type: string
        message:
          default: Invalid request
          title: Message
          type: string
      required:
        - type
        - message
      title: InvalidRequestError
      type: object
    NotFoundError:
      properties:
        type:
          default: not_found_error
          enum:
            - not_found_error
          title: Type
          type: string
        message:
          default: Not found
          title: Message
          type: string
      required:
        - type
        - message
      title: NotFoundError
      type: object
    OverloadedError:
      properties:
        type:
          default: overloaded_error
          enum:
            - overloaded_error
          title: Type
          type: string
        message:
          default: Overloaded
          title: Message
          type: string
      required:
        - type
        - message
      title: OverloadedError
      type: object
    PermissionError:
      properties:
        type:
          default: permission_error
          enum:
            - permission_error
          title: Type
          type: string
        message:
          default: Permission denied
          title: Message
          type: string
      required:
        - type
        - message
      title: PermissionError
      type: object
    RateLimitError:
      properties:
        type:
          default: rate_limit_error
          enum:
            - rate_limit_error
          title: Type
          type: string
        message:
          default: Rate limited
          title: Message
          type: string
      required:
        - type
        - message
      title: RateLimitError
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"