POST
https://octopusx.ai
/
v1beta
/
models
/
{model}
:
{action}
curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Introduce the Gemini native API in three sentences." }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 300
    }
  }'

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The Gemini native API uses contents and parts to express input content. It supports text, images, files, and function calling. With a unified gateway, you can continue using the same API key and billing system."
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 18,
    "candidatesTokenCount": 58,
    "totalTokenCount": 76
  }
}

​
Gemini Native Format

Gemini Native Format preserves the Google Gemini API paths and request bodies. It is suitable for business integrations that already use the Gemini SDK, the contents/parts structure, or safety settings configuration.

​
Authentication

Authorization: Bearer YOUR_API_KEY
Google API Key style is also supported: 
x-goog-api-key: YOUR_API_KEY
Or as a query parameter: 
/v1beta/models/gemini-2.0-flash:generateContent?key=YOUR_API_KEY

​
Paths

MethodPathDescription
GET/v1beta/modelsGemini model list
POST/v1beta/models/{model}:generateContentNon-streaming content generation
POST/v1beta/models/{model}:streamGenerateContentStreaming content generation

​
Request Body

​
contents
array<object>
required
List of conversation contents. Each content item contains role and parts.
​
contents[].parts
array<object>
required
Content parts. Supports text, inlineData, fileData, functionCall, functionResponse, and more.
​
systemInstruction
object
System-level instruction (System Prompt). Used to define model behavior, role setting, and response style. Compatible with both systemInstruction and system_instruction forms.
​
generationConfig
object
Generation configuration, used to control model output behavior. Supports the following fields:
  • temperature: Controls output randomness; higher values produce more diverse results.
  • topP: Nucleus Sampling probability threshold.
  • topK: Samples only from the top K most probable tokens.
  • candidateCount: Number of candidate results to return.
  • maxOutputTokens: Maximum number of output tokens.
  • stopSequences: Stops generation when the specified strings are encountered.
  • responseMimeType: Specifies the output format, e.g. text/plain, application/json.
  • responseSchema: JSON Schema structured output constraint.
  • presencePenalty: Reduces repetitive topics and encourages new content generation.
  • frequencyPenalty: Reduces repetitive words or sentences.
  • seed: Fixes the random seed for reproducible results.
  • responseLogprobs: Whether to return token probability information.
  • logprobs: Number of token probabilities to return.
  • audioTimestamp: Whether to return audio timestamps.
  • speechConfig: Speech output configuration (TTS).
  • thinkingConfig: Gemini Thinking model reasoning configuration.
​
safetySettings
array<object>
Safety policy configuration. Each item contains category (risk category) and threshold (risk blocking level).Supported risk categories: HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT.
​
tools
array<object>
Gemini tool declaration list, used to enable function calling, search, code execution, and other capabilities. Supports the following tool types:
  • functionDeclarations: Function Calling function declarations.
  • googleSearch: Google search capability.
  • codeExecution: Code execution capability.
  • urlContext: URL content parsing capability.
  • retrieval: Retrieval-Augmented Generation (RAG).
  • googleSearchRetrieval: Google retrieval augmentation.
​
toolConfig
object
Tool invocation configuration.Commonly used to configure functionCallingConfig.mode: AUTO (model automatically decides whether to call tools), ANY (force tool calling), NONE (disable tool calling).allowedFunctionNames: Specifies the list of functions allowed to be called.
​
cachedContent
string
Gemini Cached Content identifier. Used to reuse context cache, reducing token consumption and response latency for long-context requests.

​
Request Example

curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Introduce the Gemini native API in three sentences." }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 300
    }
  }'

​
Multimodal Input

curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Identify the core information in this image." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "BASE64_IMAGE_DATA"
            }
          }
        ]
      }
    ]
  }'

​
Streaming Generation

curl -N -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:streamGenerateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Write a release announcement in 5 lines or fewer." }
        ]
      }
    ]
  }'

​
Response Example

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The Gemini native API uses contents and parts to express input content. It supports text, images, files, and function calling. With a unified gateway, you can continue using the same API key and billing system."
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 18,
    "candidatesTokenCount": 58,
    "totalTokenCount": 76
  }
}

​
Common Safety Settings

categoryDescription
HARM_CATEGORY_HARASSMENTHarassment content
HARM_CATEGORY_HATE_SPEECHHate speech
HARM_CATEGORY_SEXUALLY_EXPLICITSexually explicit content
HARM_CATEGORY_DANGEROUS_CONTENTDangerous content
thresholdDescription
BLOCK_NONEDo not block
BLOCK_ONLY_HIGHBlock high risk only
BLOCK_MEDIUM_AND_ABOVEBlock medium risk and above
BLOCK_LOW_AND_ABOVEBlock low risk and above