多元探索 API多元探索 API
Native Format

Gemini Native Format

Use Google Gemini native paths and request bodies to call generateContent, streamGenerateContent, and model queries.

POSThttps://zx1.deepwl.net/v1beta/models/{model}:{action}
Request
curl -X POST https://zx1.deepwl.net/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
  }
}'
Response
{
  "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 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.

Request Headers

Authorizationstring必填

Authentication header. Uses a Bearer token, e.g. Bearer YOUR_API_KEY. Alternatively, you can use the x-goog-api-key header or the key query parameter.

x-goog-api-keystring

Google API Key style authentication, e.g. YOUR_API_KEY. Use either this or Authorization.

Content-Typestring必填

Request content type, must be application/json.

keystring

Google API Key style query parameter authentication, e.g. /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

contentsarray<object>必填

List of conversation contents. In multi-turn conversations, role alternates between user and model.

rolestring

Content role: user or model.

partsarray<object>必填

Content parts. Supports text, inlineData (mimeType + Base64 data), fileData (mimeType + fileUri), functionCall, functionResponse, and more.

videoMetadataobject

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.

systemInstructionobject

System-level instruction (System Prompt). Used to define model behavior, role setting, and response style. Compatible with both systemInstruction and system_instruction forms.

generationConfigobject

Generation configuration, used to control model output behavior.

temperaturenumber

Controls output randomness, range 0 to 2, defaults to 1.0. Higher values produce more diverse results.

topPnumber

Nucleus Sampling probability threshold.

topKinteger

Samples only from the top K most probable tokens.

candidateCountinteger

Number of candidate results to return. Defaults to 1.

maxOutputTokensinteger

Maximum number of output tokens.

stopSequencesarray<string>

Stops generation when the specified strings are encountered. Up to 5 sequences.

responseMimeTypestring

Specifies the output format: text/plain (default), application/json (JSON mode), text/x.enum.

responseSchemaobject

Schema constraint for structured output (a subset of OpenAPI 3.0 Schema). Must be used together with responseMimeType: application/json.

responseJsonSchemaobject

Structured output constraint in standard JSON Schema form. Mutually exclusive with responseSchema; also requires responseMimeType: application/json.

responseModalitiesarray<string>

Output modalities, e.g. ["TEXT"]; image generation models use ["TEXT", "IMAGE"].

seedinteger

Fixes the random seed for reproducible results.

presencePenaltynumber

Reduces repetitive topics and encourages new content generation.

frequencyPenaltynumber

Reduces repetitive words or sentences.

responseLogprobsboolean

Whether to return token probability information.

logprobsinteger

Number of token probabilities to return, range 0 to 20.

enableEnhancedCivicAnswersboolean

Whether to enable enhanced answers for civic-related queries such as elections and government information.

speechConfigobject

Speech output configuration (TTS), including voiceConfig, languageCode, and multi-speaker settings.

audioTimestampboolean

Whether to return audio timestamps. Only used for audio understanding scenarios.

thinkingConfigobject

Reasoning configuration for Gemini Thinking models.

includeThoughtsboolean

Whether to include thought summaries in the response.

thinkingBudgetinteger

Thinking token budget (Gemini 2.5 series). -1 enables dynamic thinking; 0 disables thinking.

thinkingLevelstring

Thinking intensity level: low, high (used by the Gemini 3 series; mutually exclusive with thinkingBudget).

mediaResolutionstring

Media input resolution: MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH. Affects token consumption and understanding fidelity for images and videos.

imageConfigobject

Image generation configuration (image generation models only). Common subfields: aspectRatio (e.g. 1:1, 16:9), imageSize (1K, 2K, 4K).

safetySettingsarray<object>

Safety policy configuration.

categorystring必填

Risk category: HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT.

thresholdstring必填

Risk blocking level: BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE.

methodstring

Scoring method: SEVERITY (by severity) or PROBABILITY (by probability).

toolsarray<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). Deprecated; only available on older models.
  • googleSearchRetrieval: Google retrieval augmentation. Use googleSearch for newer models.
toolConfigobject

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.

cachedContentstring

Gemini Cached Content identifier. Used to reuse context cache, reducing token consumption and response latency for long-context requests.

labelsobject

Custom key-value labels for request tracking and billing attribution.

Request Examples

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 (see the "Video Input" tab).

Response Examples

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