================================================================================
                    OPENAI API DOKUMENTATION
                    Vollständige Integration Guide
================================================================================

VERSION: 1.0
LAST UPDATED: 2025-10-11
BASE URL: https://theserver-open-ai.replit.app

================================================================================
                         INHALTSVERZEICHNIS
================================================================================

1. AUTHENTICATION & SETUP
2. ERROR HANDLING
3. CHAT COMPLETIONS API
4. IMAGE GENERATION API
5. AUDIO PROCESSING API
   5.1 Text-to-Speech
   5.2 Transcriptions
6. EMBEDDINGS API
7. MODERATIONS API
8. MODELS API
9. INTEGRATION GUIDE
10. BEST PRACTICES & SAFETY

================================================================================
                    1. AUTHENTICATION & SETUP
================================================================================

BASE URL:
https://theserver-open-ai.replit.app

AUTHENTICATION:
Alle API-Requests benötigen einen Authorization-Header:

  Authorization: Bearer YOUR_OPENAI_API_KEY

REQUEST HEADERS (Standard):
  Content-Type: application/json
  Authorization: Bearer sk-proj-...

SICHERHEITSHINWEISE:
  ✓ Niemals API-Keys im Client-Code hardcoden
  ✓ Verwende Environment Variables für Keys
  ✓ Implementiere Server-seitige API-Aufrufe
  ✓ Nutze Rate Limiting zum Schutz vor Missbrauch
  ✓ Verwende HTTPS für alle Requests

================================================================================
                        2. ERROR HANDLING
================================================================================

HTTP STATUS CODES:

  200 OK                  - Request erfolgreich
  400 Bad Request         - Ungültige Parameter
  401 Unauthorized        - Ungültiger API-Key
  429 Too Many Requests   - Rate Limit erreicht
  500 Internal Server     - Server-Fehler

ERROR RESPONSE FORMAT:
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

RETRY-STRATEGIE:
  - Bei 429-Fehlern: Exponential Backoff (1s, 2s, 4s, 8s...)
  - Max Retries: 3-5
  - Timeout: 30-60 Sekunden für Chat-Requests

================================================================================
                    3. CHAT COMPLETIONS API
================================================================================

ENDPOINT: POST /chat/completions

BESCHREIBUNG:
Erstelle Chat-Konversationen mit GPT-Modellen, optional mit Streaming.

PARAMETER:
  model        [REQUIRED]  String    - GPT-Modell (z.B. "gpt-4o", "gpt-4o-mini")
  messages     [REQUIRED]  Array     - Liste von Message-Objekten
  temperature  [OPTIONAL]  Number    - Kreativität 0-2 (default: 0.7)
  stream       [OPTIONAL]  Boolean   - Streaming aktivieren (default: false)
  max_tokens   [OPTIONAL]  Number    - Maximum Tokens in der Antwort

VERFÜGBARE MODELLE:
  - gpt-4o
  - gpt-4o-mini
  - gpt-4-turbo
  - gpt-3.5-turbo

MESSAGE FORMAT:
{
  "role": "system|user|assistant",
  "content": "Text content"
}

REQUEST BEISPIEL (JavaScript):
```javascript
const response = await fetch('https://theserver-open-ai.replit.app/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: 'Du bist ein hilfreicher Assistent.' },
      { role: 'user', content: 'Was ist maschinelles Lernen?' }
    ],
    temperature: 0.7,
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.trim());
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') continue;
      
      const parsed = JSON.parse(data);
      const content = parsed.choices[0]?.delta?.content;
      if (content) {
        console.log(content);
      }
    }
  }
}
```

REQUEST BEISPIEL (Python):
```python
import requests
import json

url = "https://theserver-open-ai.replit.app/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "Du bist ein hilfreicher Assistent."},
        {"role": "user", "content": "Was ist maschinelles Lernen?"}
    ],
    "temperature": 0.7,
    "stream": True
}

response = requests.post(url, headers=headers, json=data, stream=True)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            data = line[6:]
            if data == '[DONE]':
                break
            parsed = json.loads(data)
            content = parsed.get('choices', [{}])[0].get('delta', {}).get('content')
            if content:
                print(content, end='', flush=True)
```

RESPONSE FORMAT (Streaming):
data: {"choices":[{"delta":{"content":"Maschinelles"},"index":0}]}
data: {"choices":[{"delta":{"content":" Lernen"},"index":0}]}
data: {"choices":[{"delta":{"content":" ist..."},"index":0}]}
data: [DONE]

================================================================================
                    4. IMAGE GENERATION API
================================================================================

ENDPOINT: POST /images/generate

BESCHREIBUNG:
Generiere Bilder mit DALL-E basierend auf Text-Prompts.

PARAMETER:
  prompt    [REQUIRED]  String   - Beschreibung des zu generierenden Bildes
  model     [OPTIONAL]  String   - "dall-e-3" oder "dall-e-2" (default: "dall-e-3")
  size      [OPTIONAL]  String   - "1024x1024", "1792x1024", "1024x1792" (default: "1024x1024")
  quality   [OPTIONAL]  String   - "standard" oder "hd" (default: "standard")

REQUEST BEISPIEL:
```javascript
const response = await fetch('https://theserver-open-ai.replit.app/images/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    prompt: 'Ein futuristischer Roboter in einer Cyberpunk-Stadt',
    model: 'dall-e-3',
    size: '1024x1024',
    quality: 'hd'
  })
});

const data = await response.json();
console.log(data.data[0].url);
```

RESPONSE FORMAT:
{
  "created": 1711234567,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/...",
      "revised_prompt": "A futuristic robot in a cyberpunk city..."
    }
  ]
}

================================================================================
                    5. AUDIO PROCESSING API
================================================================================

--------------------- 5.1 TEXT-TO-SPEECH ---------------------

ENDPOINT: POST /audio/speech

BESCHREIBUNG:
Konvertiere Text zu Sprache mit verschiedenen Stimmen.

PARAMETER:
  input   [REQUIRED]  String  - Text der gesprochen werden soll
  voice   [REQUIRED]  String  - Stimme: "alloy", "echo", "fable", "onyx", "nova", "shimmer"
  model   [OPTIONAL]  String  - "tts-1" oder "tts-1-hd" (default: "tts-1")

VERFÜGBARE STIMMEN:
  - alloy     (neutral)
  - echo      (männlich)
  - fable     (britisch)
  - onyx      (tiefere Stimme)
  - nova      (weiblich)
  - shimmer   (hell/freundlich)

REQUEST BEISPIEL:
```javascript
const response = await fetch('https://theserver-open-ai.replit.app/audio/speech', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    input: 'Hallo, ich bin eine KI-generierte Stimme!',
    voice: 'alloy',
    model: 'tts-1-hd'
  })
});

const audioBlob = await response.blob();
const audioUrl = URL.createObjectURL(audioBlob);
const audio = new Audio(audioUrl);
audio.play();
```

RESPONSE:
Binary audio data (MP3 format)

--------------------- 5.2 TRANSCRIPTIONS ---------------------

ENDPOINT: POST /audio/transcriptions

BESCHREIBUNG:
Transkribiere Audio-Dateien zu Text mit Whisper.

PARAMETER:
  file   [REQUIRED]  File    - Audio-Datei (mp3, mp4, wav, m4a, etc.)
  model  [OPTIONAL]  String  - "whisper-1" (default)

REQUEST BEISPIEL:
```javascript
const formData = new FormData();
formData.append('file', audioFile);
formData.append('model', 'whisper-1');

const response = await fetch('https://theserver-open-ai.replit.app/audio/transcriptions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const data = await response.json();
console.log(data.text);
```

RESPONSE FORMAT:
{
  "text": "Transkribierter Text aus der Audio-Datei..."
}

================================================================================
                        6. EMBEDDINGS API
================================================================================

ENDPOINT: POST /embeddings

BESCHREIBUNG:
Generiere Vektor-Embeddings für Texte (für Semantic Search, Clustering, etc.).

PARAMETER:
  input  [REQUIRED]  String/Array  - Text(e) für Embedding-Generierung
  model  [REQUIRED]  String        - Embedding-Modell

VERFÜGBARE MODELLE:
  - text-embedding-3-small   (schnell, kosteneffizient)
  - text-embedding-3-large   (höhere Qualität)
  - text-embedding-ada-002   (legacy)

REQUEST BEISPIEL:
```javascript
const response = await fetch('https://theserver-open-ai.replit.app/embeddings', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    input: 'Maschinelles Lernen ist ein Teilgebiet der KI',
    model: 'text-embedding-3-small'
  })
});

const data = await response.json();
console.log(data.data[0].embedding);
```

RESPONSE FORMAT:
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.009, 0.015, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

VECTOR DIMENSIONEN:
  - text-embedding-3-small: 1536 Dimensionen
  - text-embedding-3-large: 3072 Dimensionen
  - text-embedding-ada-002: 1536 Dimensionen

================================================================================
                        7. MODERATIONS API
================================================================================

ENDPOINT: POST /moderations

BESCHREIBUNG:
Prüfe Texte auf potenziell problematische Inhalte.

PARAMETER:
  input  [REQUIRED]  String  - Zu prüfender Text

KATEGORIEN:
  - sexual              (sexuelle Inhalte)
  - hate                (Hassrede)
  - violence            (Gewalt)
  - self-harm           (Selbstverletzung)
  - sexual/minors       (sexuelle Inhalte mit Minderjährigen)
  - hate/threatening    (bedrohliche Hassrede)
  - violence/graphic    (grafische Gewalt)

REQUEST BEISPIEL:
```javascript
const response = await fetch('https://theserver-open-ai.replit.app/moderations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    input: 'Dies ist ein Beispieltext zur Moderation'
  })
});

const data = await response.json();
console.log(data.results[0]);
```

RESPONSE FORMAT:
{
  "id": "modr-...",
  "model": "text-moderation-007",
  "results": [
    {
      "flagged": false,
      "categories": {
        "sexual": false,
        "hate": false,
        "violence": false,
        "self-harm": false,
        "sexual/minors": false,
        "hate/threatening": false,
        "violence/graphic": false
      },
      "category_scores": {
        "sexual": 0.00001,
        "hate": 0.00001,
        "violence": 0.00001,
        "self-harm": 0.00001,
        "sexual/minors": 0.00001,
        "hate/threatening": 0.00001,
        "violence/graphic": 0.00001
      }
    }
  ]
}

================================================================================
                          8. MODELS API
================================================================================

ENDPOINT: GET /models

BESCHREIBUNG:
Rufe eine Liste aller verfügbaren OpenAI-Modelle ab.

PARAMETER:
Keine - GET Request ohne Body

REQUEST BEISPIEL:
```javascript
const response = await fetch('https://theserver-open-ai.replit.app/models', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.data);
```

RESPONSE FORMAT:
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1687882411,
      "owned_by": "openai"
    },
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1687882411,
      "owned_by": "openai"
    }
  ]
}

================================================================================
                        9. INTEGRATION GUIDE
================================================================================

SCHNELLSTART FÜR AI-AGENTS:

SCHRITT 1: API-KEY SETUP
  - Speichere OpenAI API-Key in Environment Variables
  - Nie im Code hardcoden!

SCHRITT 2: BASE URL KONFIGURIEREN
  const BASE_URL = 'https://theserver-open-ai.replit.app';

SCHRITT 3: REQUEST HEADERS SETZEN
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`
  }

SCHRITT 4: ENDPOINT AUSWÄHLEN
  - Chat: /chat/completions
  - Images: /images/generate
  - Audio: /audio/speech oder /audio/transcriptions
  - Embeddings: /embeddings
  - Moderations: /moderations
  - Models: /models

SCHRITT 5: ERROR HANDLING IMPLEMENTIEREN
  - Try/Catch Blöcke
  - Rate Limit Handling
  - Retry-Logik

CHATBOT INTEGRATION BEISPIEL:
```javascript
class OpenAIChatbot {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://theserver-open-ai.replit.app';
    this.conversationHistory = [];
  }

  async sendMessage(userMessage) {
    this.conversationHistory.push({
      role: 'user',
      content: userMessage
    });

    try {
      const response = await fetch(`${this.baseURL}/chat/completions`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.apiKey}`
        },
        body: JSON.stringify({
          model: 'gpt-4o',
          messages: this.conversationHistory,
          temperature: 0.7,
          stream: true
        })
      });

      if (!response.ok) {
        throw new Error(`API Error: ${response.status}`);
      }

      let fullResponse = '';
      const reader = response.body.getReader();
      const decoder = new TextDecoder();

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        const lines = chunk.split('\n').filter(line => line.trim());

        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const data = line.slice(6);
            if (data === '[DONE]') continue;

            const parsed = JSON.parse(data);
            const content = parsed.choices[0]?.delta?.content;
            if (content) {
              fullResponse += content;
            }
          }
        }
      }

      this.conversationHistory.push({
        role: 'assistant',
        content: fullResponse
      });

      return fullResponse;

    } catch (error) {
      console.error('Chatbot Error:', error);
      throw error;
    }
  }

  clearHistory() {
    this.conversationHistory = [];
  }
}

// Verwendung:
const bot = new OpenAIChatbot('YOUR_API_KEY');
const answer = await bot.sendMessage('Hallo!');
```

TYPESCRIPT TYPE DEFINITIONS:
```typescript
interface ChatMessage {
  role: 'system' | 'user' | 'assistant';
  content: string;
}

interface ChatCompletionRequest {
  model: string;
  messages: ChatMessage[];
  temperature?: number;
  stream?: boolean;
  max_tokens?: number;
}

interface ImageGenerationRequest {
  prompt: string;
  model?: 'dall-e-3' | 'dall-e-2';
  size?: '1024x1024' | '1792x1024' | '1024x1792';
  quality?: 'standard' | 'hd';
}

interface EmbeddingRequest {
  input: string | string[];
  model: 'text-embedding-3-small' | 'text-embedding-3-large' | 'text-embedding-ada-002';
}

interface ModerationRequest {
  input: string;
}
```

================================================================================
                   10. BEST PRACTICES & SAFETY
================================================================================

RATE LIMITING BEST PRACTICES:

✓ EXPONENTIAL BACKOFF
  Bei 429-Fehlern exponentiell warten:
  - 1. Versuch: 1 Sekunde warten
  - 2. Versuch: 2 Sekunden warten
  - 3. Versuch: 4 Sekunden warten
  - 4. Versuch: 8 Sekunden warten

✓ REQUEST QUEUING
  Implementiere eine Queue für API-Requests um Rate Limits zu vermeiden

✓ CACHING
  Cache häufige Requests um Kosten zu sparen und Limits zu schonen

✓ TIMEOUT HANDLING
  Setze angemessene Timeouts:
  - Chat Requests: 30-60 Sekunden
  - Image Generation: 60-120 Sekunden
  - Audio Transcription: 30-60 Sekunden

SAFE API CALL IMPLEMENTATION:
```javascript
async function safeAPICall(endpoint, options, maxRetries = 3) {
  let retries = 0;
  let delay = 1000;

  while (retries < maxRetries) {
    try {
      const response = await fetch(endpoint, options);

      if (response.status === 429) {
        console.log(`Rate limited. Waiting ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= 2;
        retries++;
        continue;
      }

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`API Error: ${error.error.message}`);
      }

      return response;

    } catch (error) {
      if (retries === maxRetries - 1) {
        throw error;
      }
      retries++;
      await new Promise(resolve => setTimeout(resolve, delay));
      delay *= 2;
    }
  }
}

// Verwendung:
const response = await safeAPICall(
  'https://theserver-open-ai.replit.app/chat/completions',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({...})
  }
);
```

SECURITY CHECKLIST:

☑ API-Keys niemals im Frontend-Code exponieren
☑ Verwende HTTPS für alle API-Calls
☑ Validiere und sanitize User-Inputs
☑ Implementiere Request-Rate-Limiting auf Server-Seite
☑ Logge keine sensiblen Daten (API-Keys, User-Daten)
☑ Verwende Content-Moderation für User-Generated Content
☑ Setze max_tokens Limits für Chat-Requests
☑ Monitore API-Usage und Kosten
☑ Implementiere proper Error-Logging
☑ Verwende Environment Variables für Secrets

PERFORMANCE OPTIMIERUNG:

1. STREAMING verwenden für Chat (bessere UX)
2. Kleinere Modelle für einfache Tasks (gpt-4o-mini statt gpt-4o)
3. Embeddings cachen für Semantic Search
4. Batch-Processing für mehrere Embeddings gleichzeitig
5. Image Quality "standard" statt "hd" wenn möglich

KOSTEN-OPTIMIERUNG:

- gpt-4o-mini: ~60% günstiger als gpt-4o
- text-embedding-3-small: günstiger als large-Variante
- DALL-E 2: günstiger als DALL-E 3
- tts-1: günstiger als tts-1-hd
- Cache häufige Requests
- Setze max_tokens Limits

================================================================================
                          QUICK REFERENCE
================================================================================

ENDPOINTS ÜBERSICHT:

POST   /chat/completions        → Chat Konversationen (Streaming)
POST   /images/generate          → DALL-E Bildgenerierung
POST   /audio/speech             → Text-to-Speech
POST   /audio/transcriptions     → Audio Transkription
POST   /embeddings               → Text Embeddings
POST   /moderations              → Content Moderation
GET    /models                   → Liste aller Modelle

HÄUFIG VERWENDETE PARAMETER:

Chat:
  model: "gpt-4o" | "gpt-4o-mini"
  temperature: 0.0 - 2.0 (default: 0.7)
  stream: true | false

Images:
  model: "dall-e-3" | "dall-e-2"
  size: "1024x1024" | "1792x1024" | "1024x1792"
  quality: "standard" | "hd"

Audio (TTS):
  voice: "alloy" | "echo" | "fable" | "onyx" | "nova" | "shimmer"
  model: "tts-1" | "tts-1-hd"

Embeddings:
  model: "text-embedding-3-small" | "text-embedding-3-large"

================================================================================
                            SUPPORT
================================================================================

Bei Fragen oder Problemen:
- Überprüfe die Error Response für Details
- Stelle sicher, dass API-Key gültig ist
- Checke Rate Limits und Quota
- Implementiere Retry-Logik für 429-Fehler
- Validiere Request-Parameter

Version: 1.0
Erstellt: 2025-10-11
Base URL: https://theserver-open-ai.replit.app

================================================================================
                        ENDE DER DOKUMENTATION
================================================================================