Claude Code OpenAI API: KI-Funktionen in eigene Apps integrieren

Die OpenAI API ist eine der meistgenutzten Schnittstellen für KI-Anwendungen weltweit. Chat Completions, Embeddings, DALL-E für Bilder, Whisper für Transkription, TTS für Sprachausgabe — das Ökosystem ist umfangreich, und genau das macht den Einstieg nicht immer einfach. Welches Endpoint für welchen Use Case? Wie strukturiert man das Messages-Array richtig? Wie implementiert man Streaming ohne dass es in der Produktion hängt?

Claude Code nimmt einem diese Aufgaben nicht ab — aber es beschleunigt sie erheblich. Nicht weil es die Dokumentation kennt, sondern weil es deinen bestehenden Code versteht und daraus konkrete, passgenaue Implementierungen ableitet. Dieser Artikel zeigt, wie das in der Praxis aussieht.

1. OpenAI API: Überblick über die wichtigsten Endpunkte

Bevor es in die Implementierung geht, ein kurzer Überblick über das, was die OpenAI API heute bietet:

• Chat Completions — das Kernendpoint für konversationelle KI und Textgenerierung. GPT-4o, GPT-4, GPT-3.5-turbo. Das, woran die meisten zuerst denken.
• Embeddings — numerische Repräsentationen von Text, die semantische Ähnlichkeit messbar machen. Grundlage für Vektordatenbanken und semantische Suche.
• DALL-E — Bildgenerierung aus Textprompts. Gibt es in DALL-E 2 und DALL-E 3.
• Whisper — Sprachtranskription. Unterstützt 99 Sprachen, funktioniert auch mit schlechter Audioqualität erstaunlich gut.
• TTS (Text-to-Speech) — sechs verschiedene Stimmen, realistische Ausgabe, sehr nierige Latenz für Echtzeit-Anwendungen.

In den meisten produktiven Anwendungen beginnt man mit Chat Completions und fügt Embeddings hinzu, sobald Suche oder kontextuelles Wissen gebraucht wird. DALL-E, Whisper und TTS kommen je nach Use Case dazu.

2. Setup: openai npm-Paket initialisieren

Das offizielle Node.js-Paket ist openai. Installation:

npm install openai

Die Initialisierung liest den API-Key aus der Umgebungsvariable — niemals direkt im Code:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

Wenn man Claude Code nach einem Setup fragt, erkennt es automatisch ob bereits eine .env-Datei im Projekt existiert, ob dotenv bereits als Dependency eingebunden ist, und ob es weitere bestehende API-Clients im Projekt gibt — und passt den generierten Code entsprechend an. Das ist der Unterschied zu einem generischen Code-Snippet aus der Dokumentation.

3. Chat Completions API: Messages, Rollen und Parameter

Der grundlegende Aufbau eines Chat-Completions-Aufrufs:

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'system',
      content: 'Du bist ein hilfreicher Assistent für Produktbeschreibungen.',
    },
    {
      role: 'user',
      content: 'Schreibe eine Beschreibung für einen kabellosen Kopfhörer.',
    },
  ],
  temperature: 0.7,
  max_tokens: 500,
});

const text = response.choices[0].message.content;

Die drei Rollen im Messages-Array sind das Herzstück der Konversationslogik:

• system — definiert das Verhalten des Modells für die gesamte Konversation. Persönlichkeit, Einschränkungen, Aufgabe.
• user — die Eingabe des Nutzers.
• assistant — vorherige Antworten des Modells. Für mehrstufige Konversationen werden vergangene Austausche als assistant-Nachrichten ins Array eingefügt.

temperature steuert die Kreativität: 0 = deterministisch und konsistent, 1 = kreativ und variabel. Für strukturierte Ausgaben (JSON, Code) empfiehlt sich ein niedriger Wert; für kreative Texte ein höherer. max_tokens begrenzt die Länge der Antwort und damit auch die Kosten pro Anfrage.

4. Streaming-Antworten mit stream: true

Streaming sorgt dafür, dass Text schon während der Generierung angezeigt wird — anstatt dass der Nutzer auf die vollständige Antwort wartet. Für Chat-Interfaces ist das fast immer die bessere Nutzererfahrung.

const stream = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Erkläre mir Streaming kurz.' }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content ?? '';
  process.stdout.write(delta);
}

Claude Code hilft besonders beim Aufbau der Streaming-Infrastruktur in bestehende Projekte. Wenn du Claude Code bittest, Streaming in einen vorhandenen API-Handler einzubauen, liest es den bestehenden Handler, erkennt das verwendete Framework (Express, Fastify, Next.js API Routes) und generiert den passenden Streaming-Code — inklusive korrekter Header wie Content-Type: text/event-stream und Fehlerbehandlung für abgebrochene Verbindungen.

5. Function Calling: Modell ruft deine Funktionen auf

Function Calling ist das Feature, das aus einem Sprachmodell einen handlungsfähigen Agenten macht. Das Modell entscheidet selbst, wann eine externe Funktion aufgerufen werden soll, und gibt strukturierte Parameter zurück.

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Wie ist das Wetter in Berlin?' }],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Gibt das aktuelle Wetter für eine Stadt zurück.',
        parameters: {
          type: 'object',
          properties: {
            city: {
              type: 'string',
              description: 'Name der Stadt',
            },
            unit: {
              type: 'string',
              enum: ['celsius', 'fahrenheit'],
            },
          },
          required: ['city'],
        },
      },
    },
  ],
  tool_choice: 'auto',
});

Das Erstellen korrekter JSON-Schemas für Funktionen ist fehleranfällig — falsche Typen, fehlende required-Felder, unklare Beschreibungen. Claude Code generiert diese Schemas direkt aus bestehenden TypeScript-Interfaces oder Funktionssignaturen. Zeige Claude Code deine Funktion, und es baut das korrekte parameters-Schema dafür — inklusive Beschreibungen, die das Modell verstehen kann.

6. Embeddings für semantische Suche

Embeddings transformieren Text in hochdimensionale Vektoren, die semantische Ähnlichkeit abbilden. "Hund" und "Welpe" liegen im Vektorraum nah beieinander, "Hund" und "Autobahn" weit auseinander. Das ist die Grundlage für alle RAG-Anwendungen (Retrieval-Augmented Generation).

const embedding = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Was sind die Vorteile von Vektordatenbanken?',
});

const vector = embedding.data[0].embedding;
// vector ist ein Array mit 1536 Zahlen (float)

Für Batch-Verarbeitung nimmt input auch ein Array von Strings entgegen — bis zu 2048 Texte in einem Aufruf. Das ist deutlich effizienter als einzelne Anfragen für jedes Dokument.

7. Rate Limiting und Fehlerbehandlung

Produktive OpenAI-Integrationen scheitern selten an der Logik — sie scheitern an fehlender Fehlerbehandlung für Fälle, die in der Entwicklung nicht auftreten: Rate Limits, temporäre Server-Fehler, Timeouts bei langen Antworten.

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function createCompletionWithRetry(
  messages: OpenAI.Chat.ChatCompletionMessageParam[],
  retries = 3
): Promise<string> {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      const response = await client.chat.completions.create({
        model: 'gpt-4o',
        messages,
        max_tokens: 1000,
      });
      return response.choices[0].message.content ?? '';
    } catch (error) {
      if (error instanceof OpenAI.RateLimitError) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      if (error instanceof OpenAI.APIError && error.status >= 500) {
        if (attempt === retries - 1) throw error;
        await new Promise((resolve) => setTimeout(resolve, 2000));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Maximale Anzahl Versuche erreicht');
}

Claude Code generiert dieses Boilerplate nicht als generischen Template — es passt es an deinen konkreten Kontext an. Wenn es sieht, dass dein Projekt bereits ein zentrales Error-Handling-Modul hat, wird der Retry-Code dort eingebunden statt dupliziert.

8. Wie Claude Code die API-Integration beschleunigt

Die OpenAI-Dokumentation ist gut — aber sie zeigt Beispiele in Isolation. Der eigentliche Aufwand liegt immer in der Integration: Wie passt das Chat-Completion-Endpoint in meinen bestehenden Express-Router? Wie strukturiere ich das Messages-Array für meinen spezifischen Use Case? Welche Fehler können in meiner konkreten Konfiguration auftreten?

Genau hier hilft Claude Code am meisten:

• Prompt Engineering — Claude Code liest deinen Use Case und schreibt einen System-Prompt, der das Modellverhalten korrekt steuert. Nicht generisch, sondern auf deinen Anwendungsfall zugeschnitten.
• Function Schemas — aus TypeScript-Typen oder bestehenden Funktionen direkt ein korrektes parameters-Schema generieren. Kein manuelles JSON-Schema-Schreiben mehr.
• Error Handling Boilerplate — Retry-Logik, Rate-Limit-Handling, Timeout-Behandlung für dein spezifisches Framework, nicht als abgekoppeltes Snippet.
• Streaming-Integration — erkennt das vorhandene Framework und generiert den richtigen Streaming-Code, inklusive korrekter HTTP-Header.

"Zeig mir deinen bestehenden API-Handler, dann baue ich den Streaming-Support so ein, dass er zu deiner Fehlerbehandlung passt."

Das ist der typische Claude-Code-Arbeitsablauf: nicht von der grünen Wiese, sondern in den vorhandenen Code hinein. Das macht den Unterschied zwischen einem Snippet der funktioniert und einem der tatsächlich produktionsreif ist.

• Claude Code Debugging — wie du Fehler in KI-Integrationen systematisch findest
• Claude Code für Unternehmen — API-Integrationen im Team skalieren