Gemini Generate Content API Guide

Google Gemini is a very powerful AI conversational system that can generate fluent and natural responses within seconds by entering prompts. This document mainly describes how to use the Gemini Generate Content API. This is Google's official native API format, supporting the generateContent and streamGenerateContent endpoints.

¶ Differences from the Chat Completions API

The Gemini Generate Content API uses Google's official native request format (the contents field), rather than the OpenAI-compatible format (the messages field). If you are already using the Google Gemini SDK or are familiar with the official API format, you can use this API directly without modifying the request format.

¶ Current Support Scope

The interface accepts text, image, video, and audio inputs (inlineData or fileData), thinking configuration, and custom function declarations. Native fields such as audio output, built-in tools, and explicit context caching do not yet have unified availability guarantees; please refer to the actual response of the specific model.

When submitting files such as audio using fileData.fileUri, please ensure that the files can be accessed directly via HTTPS, do not depend on a login session, and ensure that the validity period of signed links covers the entire request processing time. Non-streaming audio analysis returns results only after the model completes processing and may take more than 90 seconds; clients should set a sufficiently long total timeout based on file size and business scenarios to avoid disconnecting while the server is still processing.

¶ Application Process

Before using the Gemini Generate Content API, please first visit the Gemini Generate Content API page and click the "Get" button to obtain the credentials required for requests.

If you have not yet logged in or registered, you will be automatically redirected to the login page. The first application includes free quota.

¶ Basic Usage

¶ Non-Streaming

Send a POST request to /v1beta/models/{model}:generateContent:

Note: The flash models in the gemini-3.x series are thinking models and will consume reasoning tokens first; please set generationConfig.maxOutputTokens to 512 or above, otherwise only empty content may be returned.

curl -X POST "https://api.acedata.cloud/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "你好，请介绍一下你自己"
          }
        ]
      }
    ]
  }'

Example response:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "你好！很高兴与你交流。"}]
      },
      "finishReason": "MAX_TOKENS"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 6,
    "candidatesTokenCount": 19,
    "thoughtsTokenCount": 489,
    "totalTokenCount": 514
  },
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 19,
    "total_tokens": 514,
    "thoughts_tokens": 489,
    "cost": {
      "amount": 0.008860916380159999,
      "currency": "credit",
      "list_amount": 0.009631430847999998
    }
  },
  "modelVersion": "gemini-3.5-flash",
  "model": "gemini-3.5-flash"
}

The token fields in usageMetadata are billed according to native Gemini semantics:

• promptTokenCount includes cachedContentTokenCount; cache-hit portions are calculated at the cache read price and are not repeatedly counted as regular input.
• promptTokensDetails and cacheTokensDetails are normalized into text_tokens, image_tokens, video_tokens, audio_tokens, and the corresponding cached_* details under usage.prompt_tokens_details. These values are included in prompt_tokens and cached_tokens respectively; different modalities are recalculated only at their respective prices and are not billed repeatedly.
• Both candidatesTokenCount and thoughtsTokenCount are calculated at the output token price.
• toolUsePromptTokenCount is an independent tool input token and is calculated at the input token price.

Ace Data Cloud additionally returns a normalized usage object. Across model protocols, the cost of this call is uniformly read from usage.cost. cost is an optional cost preview; when price previews are temporarily unavailable, the model response will still be returned normally but may not include this field. The final bill is subject to usage records.

¶ Streaming

Send a POST request to /v1beta/models/{model}:streamGenerateContent?alt=sse:

curl -X POST "https://api.acedata.cloud/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "写一首关于春天的诗"
          }
        ]
      }
    ]
  }'

Streaming responses will gradually return content in SSE (Server-Sent Events) format. Intermediate events usually contain only incremental content; the final event containing authoritative usage will include usageMetadata and normalized usage, while the cost remains in usage.cost:

data: {"candidates":[{"content":{"parts":[{"text":"Hello!"}],"role":"model"},"index":0}],"modelVersion":"gemini-3.1-flash-lite","model":"gemini-3.1-flash-lite"}

data: {"candidates":[{"content":{"parts":[],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":7,"candidatesTokenCount":89,"totalTokenCount":96},"usage":{"prompt_tokens":7,"completion_tokens":89,"total_tokens":96,"cost":{"amount":0.00026161075472,"currency":"credit","list_amount":0.000284359516}},"modelVersion":"gemini-3.1-flash-lite","model":"gemini-3.1-flash-lite"}

Closing the connection indicates the end of the stream; native Gemini streams do not send data: [DONE]. If the final price preview is temporarily unavailable, usage will still return token usage but omit cost.

¶ Supported Models

¶ Advanced Features

¶ System Instructions

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "你好"}]
    }
  ],
  "systemInstruction": {
    "parts": [{"text": "你是一个专业的诗人，所有回复都用诗歌形式。"}]
  }
}

¶ Generation Configuration

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "讲一个故事"}]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 1024,
    "topP": 0.9,
    "topK": 40
  }
}

¶ JSON Mode

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "列出三个中国城市及其人口"}]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "city": {"type": "string"},
          "population": {"type": "integer"}
        }
      }
    }
  }
}

¶ Thinking Mode (Thinking)

Models that support thinking capabilities (such as gemini-2.5-flash and gemini-2.5-pro) can enable thinking mode:

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "解释量子纠缠"}]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "includeThoughts": true,
      "thinkingBudget": 2048
    }
  }
}

¶ Function Calling

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "北京现在的天气怎么样？"}]
    }
  ],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "获取指定城市的天气信息",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "城市名称"
              }
            },
            "required": ["city"]
          }
        }
      ]
    }
  ]
}

¶ Multi-turn Conversation

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "你好，我叫小明"}]
    },
    {
      "role": "model",
      "parts": [{"text": "你好小明！很高兴认识你。"}]
    },
    {
      "role": "user",
      "parts": [{"text": "我叫什么名字？"}]
    }
  ]
}

¶ Image Understanding

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "描述这张图片"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "base64_encoded_image_data..."
          }
        }
      ]
    }
  ]
}

¶ Safety Settings

Content filtering can be controlled through safetySettings:

{
  "contents": [...],
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_ONLY_HIGH"
    }
  ]
}

¶ Error Handling