Konfiguration von API-Schlüsseln, Modellauswahl und Implementierung von Function Calling mit der xAI Grok API

Die Integration von xAIs Grok-Modellen in moderne Softwareanwendungen gelingt dank vollständiger Kompatibilität mit dem OpenAI-SDK-Standard und dedizierten xAI-Bibliotheken in wenigen Schritten. Unter der einheitlichen Basis-URL https://api.x.ai/v1 ermöglicht die Grok-API eine Absicherung über standardmäßige Bearer-Token, die flexible Auswahl zwischen hochperformanten Denkmodellen wie grok-4.7 oder echtzeitfähigen Code-Engines wie grok-build-0.1 sowie mehrstufige Funktionsaufrufe (Function Calling / Tool Calling) zur direkten Anbindung von Datenbanken und Microservices.

Dieser Leitfaden führt Schritt für Schritt durch das Anlegen von API-Schlüsseln, die Auswahl des optimalen Endpunkts und die produktionsreife Implementierung von Function Calling.

1. Einrichtung der Authentifizierung und API-Schlüssel

Der Zugriff auf die Grok-API wird zentral über die xAI Console (https://console.x.ai) verwaltet.

Schritt 1: API-Schlüssel generieren

1. Melden Sie sich in der xAI Console an.
2. Laden Sie im Bereich Billing (Abrechnung) Guthaben auf, um API-Aufrufe freizuschalten.
3. Öffnen Sie die Seite API Keys (https://console.x.ai/team/default/api-keys) und klicken Sie auf Create API Key.
4. Kopieren Sie den generierten Schlüssel sofort an einen sicheren Ort; aus Sicherheitsgründen wird er nach dem Schließen des Dialogs nicht mehr vollständig angezeigt.

Schritt 2: Umgebungsvariablen definieren

Hinterlegen Sie den Schlüssel in einer Umgebungsvariable namens XAI_API_KEY:

export XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

In Node.js- oder Python-Projekten kann dies in der .env-Datei im Projektstammverzeichnis hinterlegt werden:

XAI_API_KEY=xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schritt 3: Client-SDK initialisieren

Dank der REST- und Schema-Kompatibilität können Entwickler entweder das offizielle xai-sdk, die weitverbreitete openai-Bibliothek oder das Vercel AI SDK nutzen.

Python (mit der openai-Bibliothek):

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

Python (mit dem nativen xai-sdk):

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

Node.js / TypeScript (mit der openai-Bibliothek):

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

2. Auswahl von Modell-Endpunkten und Architekturen

xAI stellt zwei primäre HTTP-Endpunkte bereit, kombiniert mit spezialisierten Modellreihen für unterschiedliche Latenz-, Kontext- und Reasoning-Anforderungen.

Endpunkt-Protokolle: /v1/responses vs. /v1/chat/completions

• https://api.x.ai/v1/responses (Empfohlener moderner Endpunkt): Konzipiert für agentische Workflows (Agentic Workflows), strukturierte Eingabearrays, zustandsbehaftetes Multi-Turn-Tracking mittels previous_response_id sowie die Orchestrierung serverseitiger Suchwerkzeuge.
• https://api.x.ai/v1/chat/completions (OpenAI-kompatibler Endpunkt): Exakt auf das gewohnte Chat-Completions-Schema abgestimmt. Ermöglicht die Migration bestehender Codebasen durch bloßes Austauschen von baseURL und apiKey.

Sprach- und Reasoning-Modelle im Überblick

Hinweis: Neben Textmodellen bietet xAI dedizierte APIs für Echtzeit-Sprachinteraktion (grok-voice-think-fast-2.0 in der Voice API) und Bild-/Videogenerierung (grok-imagine-image-2.0 in der Imagine API).

3. Implementierung von Funktionsaufrufen (Function Calling)

Function Calling macht Grok zu einem eigenständigen Agenten: Anstatt spekulative Antworten zu formulieren, erzeugt das Modell strukturierte JSON-Argumente, mit denen Ihre Anwendungslogik externe APIs ansprechen oder Datenbankabfragen durchführen kann.

Ablauf des Tool-Calling-Zyklus

1. Tool-Definition: Der Entwickler übergibt im Request ein Array an Tools mit JSON-Schema-Spezifikation (name, description, parameters).
2. Modellevaluation: Grok analysiert den Benutzerprompt und entscheidet, ob ein Tool-Aufruf zur Beantwortung notwendig ist.
3. Auslösen des Aufrufs: Das Modell stoppt die Textausgabe und liefert ein tool_calls-Objekt mit Funktionsname und JSON-Parametern zurück.
4. Lokale Ausführung: Die Anwendung führt die entsprechende Funktion auf dem eigenen Server aus.
5. Ergebnisübermittlung und Synthese: Die Ausgabedaten werden an Grok zurückgesendet, woraufhin das Modell die endgültige Antwort formuliert.

Vollständiges Implementierungsbeispiel (Python mit OpenAI-Client)

Das folgende Beispiel zeigt die Definition eines Kontoinformations-Tools am responses-Endpunkt, das Auslesen der Tool-Anforderung und die Rückgabe an grok-4.7:

import os
import json
from openai import OpenAI

# 1. Client initialisieren
client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

# 2. Tools nach JSON-Schema-Standard deklarieren
tools = [
    {
        "type": "function",
        "name": "fetch_user_account",
        "description": "Ruft Benutzerprofil, Abonnementstufe und Aktivitätsstatus anhand der Konto-ID ab.",
        "parameters": {
            "type": "object",
            "properties": {
                "account_id": {
                    "type": "string",
                    "description": "Eindeutige Konto-ID des Benutzers, z. B. 'usr_10294'"
                },
                "include_usage_stats": {
                    "type": "boolean",
                    "description": "Gibt an, ob Token-Verbrauchsdaten des laufenden Abrechnungszeitraums enthalten sein sollen.",
                    "default": False
                }
            },
            "required": ["account_id"]
        }
    }
]

# Lokale Backend-Logik
def execute_fetch_user_account(account_id: str, include_usage_stats: bool = False):
    return {
        "account_id": account_id,
        "name": "Alex Mercer",
        "tier": "Enterprise",
        "status": "Active",
        "usage_tokens": 1420500 if include_usage_stats else None
    }

# 3. Erste Benutzeranfrage absenden
user_query = "Bitte prüfe das Konto usr_10294 und gib an, ob ein aktiver Enterprise-Plan vorliegt."

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": user_query}],
    tools=tools,
)

# 4. Tool-Aufrufe verarbeiten
for item in response.output:
    if item.type == "function_call":
        func_name = item.name
        func_args = json.loads(item.arguments)
        call_id = item.call_id
        
        print(f"Modell fordert Tool an: {func_name} mit Parametern: {func_args}")
        
        if func_name == "fetch_user_account":
            tool_result = execute_fetch_user_account(**func_args)
            
            # 5. Ergebnis an Grok zurücksenden
            followup = client.responses.create(
                model="grok-4.7",
                input=[{
                    "type": "function_call_output",
                    "call_id": call_id,
                    "output": json.dumps(tool_result)
                }],
                tools=tools,
                previous_response_id=response.id,
            )
            
            # Finale konsolidierte Modellantwort ausgeben
            for followup_item in followup.output:
                if followup_item.type == "message":
                    print("\nFinale Antwort:\n", followup_item.content[0].text)

4. Architektonische Vorgaben und erweiterte Funktionen

Für den stabilen Produktiveinsatz sind folgende Spezifikationen zu beachten:

• Obligatorischer Root-Objekttyp: Im Feld parameters muss der Wurzeltyp zwingend "type": "object" sein (oder eine oneOf/anyOf-Struktur, deren Zweige jeweils Objekte darstellen). Primitive Datentypen oder Arrays an der Wurzel werden mit HTTP 400 abgewiesen.
• Parallele Funktionsaufrufe (Parallel Function Calling): Grok unterstützt standardmäßig parallele Aufrufe. Wenn eine Anfrage mehrere Datenquellen betrifft, kann das Modell mehrere Tool-Aufrufe in einem Schritt initiieren. Mit parallel_tool_calls: false kann dies auf sequenzielle Abarbeitung beschränkt werden.
• Steuerung der Tool-Auswahl (tool_choice):
  • "auto" (Standard): Das Modell entscheidet eigenständig zwischen Textantwort und Tool-Aufruf.
  • "required": Erzwingt mindestens einen Tool-Aufruf im aktuellen Durchlauf.
  • "none": Deaktiviert Tool-Aufrufe temporär.
  • {"type": "function", "function": {"name": "fetch_user_account"}}: Erzwingt den Aufruf einer festgelegten Funktion.
• Kombination aus Server- und Client-Tools: Grok erlaubt hybride Setups. Eigene Client-Funktionen können parallel zu xAI-verwalteten Server-Tools (wie {"type": "web_search"} oder {"type": "x_search"}) definiert werden. Server-Tools führt xAI automatisch aus, während Client-Tools zur lokalen Bearbeitung an Ihre Anwendung übergeben werden.
• Vollständige Chunks beim Streaming: Beim Streaming liefert Grok die Metadaten von Funktionsaufrufen in einem zusammenhängenden Block aus, wodurch ein fehleranfälliges Zusammensetzen unvollständiger JSON-Fragmente entfällt.

Referenzen

• Grok API Quickstart: Get Your API Key | SpaceXAI Docs
• Grok Models & Pricing | SpaceXAI Docs
• API Pricing | SpaceXAI Docs
• Function Calling | SpaceXAI Docs
• API Reference - REST API Reference | SpaceXAI Docs