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

{
  "error": {
    "message": "field contents is required",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_request"
  }
}

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "User quota is insufficient",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "The current request rate is too high, please try again later",
    "type": "new_api_error",
    "param": "",
    "code": "too_many_requests"
  }
}

{
  "error": {
    "message": "bad response body",
    "type": "new_api_error",
    "param": "",
    "code": "bad_response_body"
  }
}

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

{
  "error": {
    "message": "field contents is required",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_request"
  }
}

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "User quota is insufficient",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "The current request rate is too high, please try again later",
    "type": "new_api_error",
    "param": "",
    "code": "too_many_requests"
  }
}

{
  "error": {
    "message": "bad response body",
    "type": "new_api_error",
    "param": "",
    "code": "bad_response_body"
  }
}

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

Method	Path	Description
`GET`	`/v1beta/models`	Gemini model list
`POST`	`/v1beta/models/{model}:generateContent`	Non-streaming content generation
`POST`	`/v1beta/models/{model}:streamGenerateContent`	Streaming 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.

contents[].parts[].videoMetadata

object

Video input metadata. Use it on the same part as video inlineData or fileData to control the time range and frame sampling rate the model reads.Supported fields:

startOffset: Video start offset, using Duration string format, such as "3s" or "3.5s".
endOffset: Video end offset, using Duration string format, such as "10s".
fps: Video sampling frame rate. Defaults to 1.0; valid range is 0 < fps <= 24.

When a request includes multiple videos, each video part can set its own videoMetadata.

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

Video Input with videoMetadata

Put videoMetadata on the same part as the video data. It can be used to analyze only a video segment or adjust frame sampling density.

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": "Summarize what happens between seconds 3 and 12 in this video." },
          {
            "fileData": {
              "mimeType": "video/mp4",
              "fileUri": "https://example.com/demo-video.mp4"
            },
            "videoMetadata": {
              "startOffset": "3s",
              "endOffset": "12s",
              "fps": 2
            }
          }
        ]
      }
    ]
  }'

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

{
  "error": {
    "message": "field contents is required",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_request"
  }
}

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "User quota is insufficient",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "The current request rate is too high, please try again later",
    "type": "new_api_error",
    "param": "",
    "code": "too_many_requests"
  }
}

{
  "error": {
    "message": "bad response body",
    "type": "new_api_error",
    "param": "",
    "code": "bad_response_body"
  }
}

Common Safety Settings

category	Description
`HARM_CATEGORY_HARASSMENT`	Harassment content
`HARM_CATEGORY_HATE_SPEECH`	Hate speech
`HARM_CATEGORY_SEXUALLY_EXPLICIT`	Sexually explicit content
`HARM_CATEGORY_DANGEROUS_CONTENT`	Dangerous content

threshold	Description
`BLOCK_NONE`	Do not block
`BLOCK_ONLY_HIGH`	Block high risk only
`BLOCK_MEDIUM_AND_ABOVE`	Block medium risk and above
`BLOCK_LOW_AND_ABOVE`	Block low risk and above

Claude Messages API Image Series Overview

Overview

Text Models

Image Models

Video Models

Uploads

Tasks

Account

Gemini Native Format

Gemini Native Format

Authentication

Paths

Request Body

Request Example

Multimodal Input

Video Input with videoMetadata

Streaming Generation

Response Example

Common Safety Settings

​Gemini Native Format

​Authentication

​Paths

​Request Body

​Request Example

​Multimodal Input

​Video Input with videoMetadata

​Streaming Generation

​Response Example

​Common Safety Settings

​Related Interfaces

Gemini Native Format

Authentication

Paths

Request Body

Request Example

Multimodal Input

Video Input with videoMetadata

Streaming Generation

Response Example

Common Safety Settings

Related Interfaces