Anleitung zur Gemini Generate Content API

Google Gemini ist ein sehr leistungsstarkes KI-Dialogsystem, das durch die Eingabe von Prompts innerhalb weniger Sekunden flüssige und natürliche Antworten generieren kann. Dieses Dokument beschreibt hauptsächlich die Verwendung der Gemini Generate Content API. Dies ist das offizielle native API-Format von Google und unterstützt die beiden Endpunkte generateContent und streamGenerateContent.

Unterschiede zur Chat Completions API

Die Gemini Generate Content API verwendet das offizielle native Anfrageformat von Google (Feld contents) statt des OpenAI-kompatiblen Formats (Feld messages). Wenn du bereits das Google Gemini SDK verwendest oder mit dem offiziellen API-Format vertraut bist, kannst du diese API direkt verwenden, ohne das Anfrageformat ändern zu müssen.

Aktuell unterstützter Umfang

Die Schnittstelle akzeptiert Text-, Bild-, Video- und Audioeingaben (inlineData oder fileData), Denk-Konfigurationen sowie benutzerdefinierte Funktionsdeklarationen. Für Audioausgaben, integrierte Tools und native Felder wie explizites Kontext-Caching besteht derzeit keine einheitliche Verfügbarkeitsgarantie; maßgeblich ist die tatsächliche Rückgabe des jeweiligen Modells. Wenn du Dateien wie Audio über fileData.fileUri übermittelst, stelle sicher, dass die Datei direkt über HTTPS zugänglich ist, nicht von einem Login-Status abhängt und die Gültigkeitsdauer des signierten Links die gesamte Verarbeitungszeit der Anfrage abdeckt. Bei nicht-streamender Audioanalyse wird das Ergebnis erst zurückgegeben, nachdem das Modell die Verarbeitung abgeschlossen hat, was mehr als 90 Sekunden dauern kann; der Client sollte je nach Dateigröße und Geschäftsszenario einen ausreichend langen Gesamt-Timeout festlegen, um zu vermeiden, dass die Verbindung getrennt wird, während der Server noch verarbeitet.

Antragsprozess

Bevor du die Gemini Generate Content API verwendest, besuche bitte die Seite Gemini Generate Content API und klicke auf die Schaltfläche „Abrufen“, um die für die Anfrage erforderlichen Zugangsdaten zu erhalten. Falls du noch nicht angemeldet oder registriert bist, wirst du automatisch zur Anmeldeseite weitergeleitet. Bei der ersten Beantragung gibt es ein kostenloses Kontingent.

Grundlegende Verwendung

Non-Streaming (nicht-streamend)

Sende eine POST-Anfrage an /v1beta/models/{model}:generateContent:

Hinweis: Flash der Serie gemini-3.x ist ein Denkmodell und verbraucht zuerst Reasoning-Tokens; setze generationConfig.maxOutputTokens auf mindestens 512, da andernfalls möglicherweise nur leere Inhalte zurückgegeben werden.

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": "你好，请介绍一下你自己"
          }
        ]
      }
    ]
  }'

Beispiel für das Rückgabeergebnis:

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

Die Token-Felder in usageMetadata werden gemäß der nativen Gemini-Semantik abgerechnet:

promptTokenCount enthält cachedContentTokenCount; der aus dem Cache abgerufene Teil wird zum Preis für Cache-Lesezugriffe berechnet und nicht erneut als reguläre Eingabe gezählt.
promptTokensDetails und cacheTokensDetails werden unter usage.prompt_tokens_details in text_tokens, image_tokens, video_tokens, audio_tokens sowie die entsprechenden cached_*-Details normalisiert. Diese Werte sind jeweils in prompt_tokens und cached_tokens enthalten; unterschiedliche Modalitäten werden nur nach ihren jeweiligen Preisen neu berechnet und nicht doppelt abgerechnet.
candidatesTokenCount und thoughtsTokenCount werden beide zum Preis für Ausgabe-Tokens berechnet.
toolUsePromptTokenCount sind eigenständige Tool-Eingabe-Tokens und werden zum Preis für Eingabe-Tokens berechnet.

Ace Data Cloud gibt zusätzlich ein normalisiertes usage-Objekt zurück; modellübergreifend werden die Kosten dieses Aufrufs einheitlich aus usage.cost gelesen. cost ist eine optionale Kostenvorschau; wenn die Preisvorschau vorübergehend nicht verfügbar ist, wird die Modellantwort dennoch normal zurückgegeben, kann dieses Feld jedoch nicht enthalten. Die endgültige Abrechnung richtet sich nach den Nutzungsaufzeichnungen.

Streaming (streamend)

Sende eine POST-Anfrage an /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": "写一首关于春天的诗"
          }
        ]
      }
    ]
  }'

Die Stream-Rückgabe liefert Inhalte schrittweise im SSE-Format (Server-Sent Events) zurück. Zwischenereignisse enthalten normalerweise nur inkrementelle Inhalte; das Endereignis mit verbindlichen Nutzungsdaten enthält usageMetadata und das normalisierte usage, die Kosten befinden sich weiterhin 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"}

Das Schließen der Verbindung zeigt das Ende des Streams an; native Gemini-Streams senden kein data: [DONE]. Wenn die Preisvorschau des Endzustands vorübergehend nicht verfügbar ist, gibt usage weiterhin die Token-Nutzung zurück, lässt jedoch cost weg.

Unterstützte Modelle

Modellname	Beschreibung
`gemini-3.8-flash`	Neuestes Flash-Modell, geeignet für hochwertige allgemeine Aufgaben
`gemini-3.7-flash`	Hochwertiges allgemeines Flash-Modell
`gemini-3.6-flash`	Stabiles, leistungsstarkes multimodales Modell
`gemini-3.5-flash`	Multimodales Modell mit hohem Durchsatz
`gemini-3.5-flash-lite`	Modell mit geringer Latenz und niedrigen Kosten
`gemini-3.1-flash-lite`	Stabile Version eines schlanken Modells
`gemini-3.1-pro-preview`	Modell für komplexes Schlussfolgern und Programmieren
`gemini-3-flash-preview`	Gemini 3 Flash-Vorschaumodell
`gemini-2.5-pro`	Gemini 2.5 Pro-Modell
`gemini-2.5-flash`	Gemini 2.5 Flash-Modell
`gemini-2.5-flash-lite`	Gemini 2.5 Flash-Lite-Modell
`gemini-3.1-flash-image`	Modell zur Bildgenerierung
`gemini-3-pro-image`	Modell zur hochwertigen Bildgenerierung
`gemini-2.5-flash-image`	Gemini 2.5 Modell zur Bildgenerierung

Erweiterte Funktionen

Systemanweisungen

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

Generierungskonfiguration

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

JSON-Modus

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

Denkmodus (Thinking)

Modelle, die die Denkfunktion unterstützen (wie gemini-2.5-flash, gemini-2.5-pro), können den Denkmodus aktivieren:

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

Funktionsaufruf

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

Mehrturn-Dialog

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

Bildverständnis

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

Sicherheitseinstellungen

Die Inhaltsfilterung kann über safetySettings gesteuert werden:

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

Fehlerbehandlung

HTTP-Statuscode	Bedeutung
400	Ungültige Anfrageparameter
401	Authentifizierung fehlgeschlagen, bitte Token überprüfen
403	Inhalt wurde vom Sicherheitsfilter abgefangen
429	Anfrage zu häufig
500	Interner Serverfehler

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

Anleitung zur Gemini Generate Content API

Unterschiede zur Chat Completions API

Aktuell unterstützter Umfang

Antragsprozess

Grundlegende Verwendung

Non-Streaming (nicht-streamend)

Streaming (streamend)

Unterstützte Modelle

Erweiterte Funktionen

Systemanweisungen

Generierungskonfiguration

JSON-Modus

Denkmodus (Thinking)

Funktionsaufruf

Mehrturn-Dialog

Bildverständnis

Sicherheitseinstellungen

Fehlerbehandlung

​Unterschiede zur Chat Completions API

​Aktuell unterstützter Umfang

​Antragsprozess

​Grundlegende Verwendung

​Non-Streaming (nicht-streamend)

​Streaming (streamend)

​Unterstützte Modelle

​Erweiterte Funktionen

​Systemanweisungen

​Generierungskonfiguration

​JSON-Modus

​Denkmodus (Thinking)

​Funktionsaufruf

​Mehrturn-Dialog

​Bildverständnis

​Sicherheitseinstellungen

​Fehlerbehandlung

Unterschiede zur Chat Completions API

Aktuell unterstützter Umfang

Antragsprozess

Grundlegende Verwendung

Non-Streaming (nicht-streamend)

Streaming (streamend)

Unterstützte Modelle

Erweiterte Funktionen

Systemanweisungen

Generierungskonfiguration

JSON-Modus

Denkmodus (Thinking)

Funktionsaufruf

Mehrturn-Dialog

Bildverständnis

Sicherheitseinstellungen

Fehlerbehandlung