TokenLab

Gemini Native

Generate Content

Generates content using Google Gemini API format

POST
/v1beta/models/{model}:generateContent

Use Gemini request and response formats with a model returned by List Models. ProtoJSON lowerCamelCase and the corresponding proto snake_case field names are accepted. Supported optional fields and values depend on the selected model.

Path Parameters

modelstringpathrequired

Model name (e.g., gemini-2.5-pro, gemini-3.5-flash).

Query Parameters

keystringquery

API key (alternative to header authentication).

Authentication

Gemini endpoints support multiple authentication methods:

  • ?key=YOUR_API_KEY query parameter
  • x-goog-api-key: YOUR_API_KEY header
  • Authorization: Bearer YOUR_API_KEY header

Request Body

contentsarrayrequired

Conversation contents with parts and an optional role. Media parts use inlineData / inline_data or fileData / file_data. Files and Cache IDs created by TokenLab can only be used in their owning Workspace.

systemInstructionobject

System instruction for the model.

generationConfigobject

Generation settings such as temperature, topP, topK, maxOutputTokens, stopSequences, candidateCount, responseModalities, responseMimeType, responseSchema, and thinkingConfig. Corresponding snake_case names are also accepted. Supported values and combinations depend on the model.

safetySettingsarray

Safety filter settings.

toolsarray

Gemini tools such as functionDeclarations. Supported tool types depend on the model.

toolConfigobject

Tool configuration such as functionCallingConfig.

cachedContentstring

Name of cached content created with Create cached content, for example cachedContents/abc123. It works only in the Workspace that created it.

Every lowerCamelCase field shown above may also use its official proto snake_case spelling, for example system_instruction, generation_config, safety_settings, tool_config, cached_content, file_data.file_uri, and inline_data.mime_type.

Supported Methods

The Gemini-compatible API includes List Models, Get Model, generateContent, streamGenerateContent, countTokens, Files, and cached content. Gemini Interactions and Live are not available.

Read the model's Get Model response before calling it: supportedGenerationMethods lists the actions that model accepts.

Response

candidatesarray

Generated content candidates.

usageMetadataobject

Token usage information.

Request

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
    }
  }'

Errors

  • 400 INVALID_ARGUMENT: the body is not valid, or the model does not accept Gemini requests.
  • 401 UNAUTHENTICATED: the API key is missing or invalid.
  • 402 RESOURCE_EXHAUSTED: the balance is too low for this request.
  • 503 UNAVAILABLE: no route is available for the model right now. Retry later.

Media Input

Place media inside contents[].parts[] as inline Base64 bytes (inlineData or inline_data) or as a public https URL (fileData or file_data). Image, audio, and video are supported.

Image

Use inline image bytes:

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

Use an image URL:

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

Audio

Use an audio URL, here with the proto snake_case names:

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

Video

Use a video URL:

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

Response

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
  }
}

Token counting and embeddings

Count Tokens (POST /v1beta/models/{model}:countTokens) needs an API key and is not billed. Use the count for planning; the charge for a generation request comes from that response's usageMetadata.

Embedding models use Create Embedding (POST /v1/embeddings). Call embedContent or batchEmbedContents only for a model whose Get Model response lists them in supportedGenerationMethods.

Authorization

AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Path Parameters

model*string

Model name (e.g., gemini-2.5-pro)

Query Parameters

key?string

API key (alternative to header auth)

Headers

X-TokenLab-Delivery-Policy?string

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Value in

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

Request Body

application/json

Native Gemini GenerateContent request. ProtoJSON lowerCamelCase and original proto snake_case names are both accepted and preserved, including mixed requests. If both spellings of one field are present, TokenLab does not merge them or choose a local precedence. Unknown fields are forwarded on a best-effort basis.

Response

application/json

application/json

application/json

application/json

application/json

application/json