API-ul Open WebUI: chei API, /api/models și /api/chat/completions în Open WebUI & RAG Local

curl -H "Authorization: Bearer CHEIA_TA" http://localhost:3000/api/models

Cheile API trebuie activate: administratorul pornește API Keys în Settings > Admin > Authentication (ENABLE_API_KEYS, oprit implicit), iar utilizatorii obișnuiți au nevoie și de permisiunea API Keys din permisiunile implicite sau dintr-un grup. Cheia se generează din Settings > Account. Fiecare cont are o singură cheie, care acționează ca acel utilizator, cu rolul și permisiunile lui verificate la fiecare cerere. Opțional, API Key Endpoint Restrictions limitează rutele pe care le pot apela cheile.

GET /api/models listează modelele, iar POST /api/chat/completions primește corpul OpenAI Chat Completions pentru orice model din Open WebUI, inclusiv presetările din Workspace și Pipe-urile. Parametrii trimiși în cerere (temperature, max_tokens, seed etc.) au prioritate față de cei ai presetării. În usage, prompt_tokens și completion_tokens descriu doar ultimul apel de model, iar input_tokens, output_tokens și total_tokens tot răspunsul, cu toate apelurile de unelte. Mai există /api/v1/messages (formatul Anthropic Messages) și un proxy către API-ul nativ Ollama la /ollama/api/....

Pentru RAG prin API: POST /api/v1/files/ încarcă un fișier (procesarea rulează implicit în fundal), GET /api/v1/files/{id}/process/status se interoghează până la completed, apoi POST /api/v1/knowledge/{id}/file/add îl adaugă la o bază. În /api/chat/completions, câmpul files primește {"type": "file", "id": ...} sau {"type": "collection", "id": ...}. Documentația interactivă Swagger (/docs) apare doar cu ENV=dev; imaginea Docker pornește cu ENV=prod.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
Authorization: Bearer ...	Cheia API sau un JWT. Dacă un proxy folosește deja antetul Authorization, cheia se poate trimite în antetul x-api-key (numele se schimbă cu CUSTOM_API_KEY_HEADER).
ENABLE_API_KEYS	Comutatorul global; oprit, nicio cheie nu mai autentifică, nici cele existente.
GET /api/models	Toate modelele vizibile pentru utilizatorul cheii.
POST /api/chat/completions	Chat compatibil OpenAI; acceptă și files.
POST /api/v1/files/	Încărcare de fișier; parametrii process și process_in_background (ambii implicit true).
GET /api/v1/files/{id}/process/status	Starea procesării: pending, completed sau failed; cu ?stream=true trimite Server-Sent Events.
POST /api/v1/knowledge/{id}/file/add	Adaugă un fișier procesat într-o bază Knowledge.
/api/v1/models/export, /import, /sync	Export și import JSON al presetărilor; sync (doar admin) face instanța identică cu lista trimisă, deci și șterge.
/ollama/api/...	Proxy către API-ul Ollama (de exemplu /ollama/api/tags).

Exemple practice și scenarii reale

Exemplul 1: Chat prin API

ID-ul modelului este cel din Open WebUI; pentru o conexiune OpenAI este ID-ul furnizorului.

curl -X POST http://localhost:3000/api/chat/completions \
  -H "Authorization: Bearer CHEIA_TA" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-6-luna",
        "messages": [{"role": "user", "content": "Explică pe scurt ce este RAG."}]
      }'

Exemplul 2: Încărcare, așteptare și întrebare despre un fișier

Adăugarea într-o bază înainte de completed întoarce eroarea 400 „The content provided is empty”.

# 1. Încărcare: răspunsul conține "id"
curl -X POST -H "Authorization: Bearer CHEIA_TA" -H "Accept: application/json" \
  -F "file=@regulament.pdf" http://localhost:3000/api/v1/files/

# 2. Starea procesării, până la "completed"
curl -H "Authorization: Bearer CHEIA_TA" \
  http://localhost:3000/api/v1/files/ID_FISIER/process/status

# 3. Întrebare cu fișierul atașat
curl -X POST http://localhost:3000/api/chat/completions \
  -H "Authorization: Bearer CHEIA_TA" -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-luna",
       "messages": [{"role": "user", "content": "Câte zile de concediu prevede documentul?"}],
       "files": [{"type": "file", "id": "ID_FISIER"}]}'

Exemplul 3: Modelele unui server Ollama prin proxy

curl -H "Authorization: Bearer CHEIA_TA" http://localhost:3000/ollama/api/tags

Greșeli frecvente și capcane

• Adaugi fișierul într-o bază Knowledge imediat după încărcare. Procesarea e asincronă; aștepți starea completed.
• Facturezi după prompt_tokens / completion_tokens. La răspunsurile cu unelte ele acoperă doar ultimul apel; pentru total folosești input_tokens / output_tokens.
• Cauți /docs pe o instalare Docker: Swagger apare doar cu ENV=dev.

Noțiuni și module înrudite

• open-webui-workspace-modele
• rag-document-upload
• user-roles-permissions
• conectare-openai-vllm