> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Completion API

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

<Info>
  **⚠️ Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

# Google Completion Endpoint (v1beta)

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:

<Steps>
  <Step title="Get available models">
    Call <code>GET /`{region}`/v1beta/models/</code> to retrieve the list of Gemini models.
  </Step>

  <Step title="Pick a model & action">
    Choose a model ID and decide between <code>generateContent</code> or <code>streamGenerateContent</code>.
  </Step>

  <Step title="Send your request">
    POST to <code>/`{region}`/v1beta/models/`{model}`:`{action}`</code> with your prompt in <code>contents</code>.
  </Step>

  <Step title="Handle the response">
    Parse the JSON response for normal calls or consume the SSE events for streaming.
  </Step>
</Steps>

• 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 Langdock API Key:

<ParamField name="Authorization" type="string" required>
  Bearer \<LANGDOCK\_API\_KEY>
</ParamField>

<ParamField name="x-api-key" type="string" required={false}>
  Alternative header for the same API key.
</ParamField>

<ParamField name="x-goog-api-key" type="string" required={false}>
  Convenience header used by the official **google-generative-ai** Python SDK.
</ParamField>

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

**Authorization header example:**

```bash theme={null}
curl -H "Authorization: Bearer $LD_API_KEY" \
     https://api.langdock.com/google/eu/v1beta/models
```

**x-api-key header example:**

```bash theme={null}
curl -H "x-api-key: $LD_API_KEY" \
     https://api.langdock.com/google/eu/v1beta/models
```

**x-goog-api-key header example:**

```bash theme={null}
curl -H "x-goog-api-key: $LD_API_KEY" \
     https://api.langdock.com/google/eu/v1beta/models
```

***

## 1. List available models

### GET `/{region}/v1beta/models`

`region` must be `eu` or `us`.

#### Successful response

<ResponseField name="models" type="array">
  List of objects with the following shape:

  * **name** – Fully-qualified model name (e.g. `models/gemini-2.5-flash`).
  * **supportedGenerationMethods** – Always `["generateContent", "streamGenerateContent"]`.
</ResponseField>

```bash theme={null}
curl -H "Authorization: Bearer $LD_API_KEY" \
     https://api.langdock.com/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`](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference) structure.

#### Required fields

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

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

**`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 theme={null}
"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 theme={null}
"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 theme={null}
"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 theme={null}
"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 theme={null}
"systemInstruction": {
  "role": "system",
  "parts": [
    {
      "text": "You are a weather agent. Use the weather tool when asked about weather."
    }
  ]
}
```

<Info>
  If `toolConfig.functionCallingConfig.allowedFunctionNames` is provided, `mode` **must** be `ANY`.
</Info>

#### Minimal example

```bash theme={null}
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $LD_API_KEY" \
     https://api.langdock.com/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..." }]
      }
    }
  ]
}
```

{/* A JSON array wrapper (`[ ... ]`) is sent around the event stream so that the
response can be consumed directly by the Google Python SDK. This might cause issues
with the first chunk event. */}

**Python SDK example with function calling:**

```python theme={null}
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_LANGDOCK_API_KEY>",

    transport="rest",  
    client_options={"api_endpoint": "https://api.langdock.com/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 theme={null}
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.

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml POST /google/{region}/v1beta/models/{model}:generateContent
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
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: The content to generate a response for.
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - model
                      parts:
                        type: array
                        items:
                          type: object
                          properties:
                            text:
                              type: string
              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"

````