راهنمای اتصال OpenWebUI به API گپ جی‌پی‌تی

این راهنما برای زمانی است که می‌خواهید OpenWebUI را به عنوان رابط کاربری خودمیزبان استفاده کنید، اما مدل‌ها، پرداخت ریالی، لاگ مصرف و مدیریت کلید را از API گپ جی‌پی‌تی بگیرید. OpenWebUI با APIهای سازگار با OpenAI کار می‌کند و اتصال اصلی گپ جی‌پی‌تی هم از همین مسیر انجام می‌شود.

نکته مهم: خود OpenWebUI می‌تواند روی سرور یا کامپیوتر شما اجرا شود، اما وقتی گپ جی‌پی‌تی را به عنوان Provider تنظیم می‌کنید، متن، تصویر، صدا و فایل‌هایی که برای مدل ارسال می‌شوند از OpenWebUI به API گپ جی‌پی‌تی فرستاده می‌شوند. بنابراین این حالت «کاملاً آفلاین» نیست.

۱. پیش‌نیازها

برای شروع به این موارد نیاز دارید:

برای ساخت کلید:

  1. وارد بخش کلیدهای API شوید.
  2. یک کلید جدید بسازید.
  3. کلید را همان لحظه در جای امن نگه دارید؛ این مقدار بعداً دوباره کامل نمایش داده نمی‌شود.

مقادیر اصلی اتصال:

گزینه مقدار
Base URL https://api.gapgpt.app/v1
Authentication Bearer YOUR_GAPGPT_API_KEY
نوع اتصال در OpenWebUI OpenAI-compatible / Standard
Azure خاموش / استفاده نشود

در فیلد API Key خود OpenWebUI فقط مقدار کلید گپ جی‌پی‌تی را وارد کنید؛ Bearer را به ابتدای آن اضافه نکنید. OpenWebUI هنگام درخواست، خودش Header را به شکل Bearer می‌سازد.

اگر در شبکه یا CDN خاصی نیاز به مسیر جایگزین دارید، در مستندات شروع سریع گپ جی‌پی‌تی مسیر https://api.gapapi.com/v1 هم به عنوان گزینه جایگزین ذکر شده است؛ اما برای شروع همان https://api.gapgpt.app/v1 را تنظیم کنید.

۲. نصب سریع OpenWebUI

اگر OpenWebUI را از قبل نصب نکرده‌اید، ساده‌ترین مسیر Docker است:

docker run -d \
  -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

سپس آدرس زیر را باز کنید:

http://localhost:3000

روش‌های دیگر مثل pip install open-webui یا uvx open-webui هم پشتیبانی می‌شوند. برای محیط production بهتر است از Docker یا نصب Python پایدار استفاده کنید و داده OpenWebUI را روی volume دائمی نگه دارید.

۳. اتصال مدل‌های متنی و چت

این بخش اتصال اصلی OpenWebUI به مدل‌های متنی، مدل‌های vision و مدل‌های دارای function calling است.

  1. در OpenWebUI وارد حساب Admin شوید.
  2. از پایین صفحه روی پروفایل خود کلیک کنید و وارد Admin Panel شوید.
  3. به مسیر Settings > Connections بروید.
  4. در بخش OpenAI روی گزینه Manage یا آیکن آچار کلیک کنید.
  5. روی Add New Connection بزنید.
  6. نوع اتصال را روی حالت Standard / Compatible بگذارید، نه Azure.
  7. این مقادیر را وارد کنید:
Connection Type: External
URL: https://api.gapgpt.app/v1
API Key: YOUR_GAPGPT_API_KEY
  1. اگر فیلد API Version وجود دارد، آن را خالی بگذارید.
  2. اگر فقط می‌خواهید چند مدل مشخص دیده شوند، در Model IDs / Model IDs Filter نام دقیق مدل‌ها را وارد کنید.
  3. ذخیره کنید.

OpenWebUI معمولاً مدل‌ها را از مسیر GET /v1/models می‌خواند. گپ جی‌پی‌تی این مسیر را روی API عمومی پشتیبانی می‌کند. اگر لیست مدل‌ها نمایش داده نشد یا می‌خواهید صفحه انتخاب مدل سبک‌تر باشد، مدل‌ها را دستی در Model IDs Filter وارد کنید.

نمونه Model IDs:

gpt-4o
gpt-4o-mini
gemini-2.5-pro
gapgpt-deepseek-v4.1-flash
claude-sonnet-5

نام مدل‌ها ممکن است تغییر کند. برای انتخاب دقیق مدل، همیشه صفحه مدل‌ها و قیمت‌ها را معیار قرار دهید.

نکته درباره Prefix ID

اگر در OpenWebUI فقط گپ جی‌پی‌تی را به عنوان OpenAI-compatible provider دارید، Prefix ID را خالی بگذارید. اگر چند Provider دارید و نام مدل‌ها با هم تداخل دارند، می‌توانید Prefix بگذارید، اما در این حالت همان نام prefixدار در Model Selector دیده می‌شود.

تست سریع اتصال

پس از ذخیره اتصال، یک چت جدید باز کنید و یکی از مدل‌های گپ جی‌پی‌تی را از Model Selector انتخاب کنید. سپس پیام کوتاهی بفرستید:

سلام! خودت را در یک جمله معرفی کن.

اگر مدل پاسخ داد، اتصال چت درست است. اگر خطای 401 گرفتید، کلید API اشتباه است یا با Bearer درست ارسال نشده است. اگر مدل‌ها دیده نمی‌شوند، Model IDs Filter را دستی تنظیم کنید.

۴. تنظیم با Environment Variable

اگر OpenWebUI را با Docker Compose یا Kubernetes اجرا می‌کنید، می‌توانید اتصال گپ جی‌پی‌تی را از ابتدا با environment variable بسازید:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      ENABLE_OPENAI_API: "True"
      OPENAI_API_BASE_URLS: "https://api.gapgpt.app/v1"
      OPENAI_API_KEYS: "YOUR_GAPGPT_API_KEY"
      ENABLE_BASE_MODELS_CACHE: "True"

volumes:
  open-webui:

اگر چند OpenAI-compatible provider دارید، OPENAI_API_BASE_URLS و OPENAI_API_KEYS را با ; جدا کنید و ترتیبشان را یکی نگه دارید:

OPENAI_API_BASE_URLS=https://api.openai.com/v1;https://api.gapgpt.app/v1
OPENAI_API_KEYS=OPENAI_KEY;GAPGPT_API_KEY

OpenWebUI بعضی تنظیمات را بعد از اجرای اول در دیتابیس خودش نگه می‌دارد. اگر یک مقدار را در env تغییر دادید ولی UI همچنان مقدار قبلی را نشان داد، از داخل Admin Panel مقدار را تغییر دهید یا فقط در صورتی که دقیقاً می‌دانید چه می‌کنید ENABLE_PERSISTENT_CONFIG=False بگذارید. در حالت دوم تغییرات UI بعد از restart باقی نمی‌مانند.

۵. مدل‌های متنی، Vision و ابزارها

OpenWebUI برای چت معمولی از مسیر زیر استفاده می‌کند:

POST https://api.gapgpt.app/v1/chat/completions

این مسیر برای مدل‌های متنی و بسیاری از مدل‌های چندرسانه‌ای استفاده می‌شود. نکات مهم:

در گپ جی‌پی‌تی مسیر /v1/responses هم در API عمومی وجود دارد، اما اتصال معمول OpenWebUI برای OpenAI-compatible provider بر پایه Chat Completions است. فقط وقتی سراغ Open Responses بروید که در نسخه OpenWebUI شما اتصال Open Responses جداگانه فعال است و مدل مدنظر را جداگانه تست کرده‌اید.

۶. Embedding و RAG در OpenWebUI

OpenWebUI برای RAG می‌تواند Embedding را از OpenAI-compatible API بگیرد. در گپ جی‌پی‌تی مسیر مربوطه این است:

POST https://api.gapgpt.app/v1/embeddings

تنظیم از UI:

  1. وارد Admin Panel > Settings > Documents شوید.
  2. بخش Embedding را روی OpenAI یا OpenAI-compatible بگذارید.
  3. Base URL را وارد کنید:
https://api.gapgpt.app/v1
  1. API Key گپ جی‌پی‌تی را وارد کنید.
  2. مدل embedding را از صفحه مدل‌ها و قیمت‌ها انتخاب کنید؛ برای مثال اگر در لیست فعال بود:
gemini-embedding-001

تنظیم با env:

RAG_EMBEDDING_ENGINE=openai
RAG_OPENAI_API_BASE_URL=https://api.gapgpt.app/v1
RAG_OPENAI_API_KEY=YOUR_GAPGPT_API_KEY
RAG_EMBEDDING_MODEL=gemini-embedding-001
RAG_EMBEDDING_OPENAI_BATCH_SIZE=1

اگر مدل embedding انتخابی prefix خاصی برای document/query لازم دارد، فقط طبق مستندات همان مدل مقدارهای RAG_EMBEDDING_CONTENT_PREFIX و RAG_EMBEDDING_QUERY_PREFIX را تنظیم کنید. برای مدل‌هایی که چنین نیازی ندارند، این فیلدها را خالی بگذارید.

۷. تولید تصویر

تولید تصویر در OpenWebUI جدا از Provider چت تنظیم می‌شود. حتی اگر چت متنی کار می‌کند، برای تصویر باید بخش Images را هم فعال کنید.

  1. وارد Admin Panel > Settings > Images شوید.
  2. گزینه Image Generation را فعال کنید.
  3. مقدار Image Generation Engine را روی OpenAI یا Open AI بگذارید.
  4. این مقادیر را تنظیم کنید:
API Base URL: https://api.gapgpt.app/v1
API Key: YOUR_GAPGPT_API_KEY
Image Generation Model: gpt-image-2
Image Size: 1024x1024

می‌توانید به جای gpt-image-2 از هر مدل تصویری فعال در صفحه قیمت‌ها استفاده کنید. برای مثال اگر در لیست شما فعال است، gapgpt/qwen-image-2.1 هم یک مدل تصویری گپ جی‌پی‌تی است.

نکته مهم درباره خروجی URL و Base64

در بسیاری از مدل‌های تصویر گپ جی‌پی‌تی، پاسخ نهایی شامل URL فایل تولیدشده است. OpenWebUI برای مدل‌هایی که نامشان با gpt-image شروع می‌شود، طبق تنظیم پیش‌فرض خودش انتظار URL را درست‌تر مدیریت می‌کند. برای مدل‌هایی مثل gapgpt/qwen-image-2.1 که با gpt-image شروع نمی‌شوند، اگر OpenWebUI خطای مربوط به response_format: b64_json یا نمایش ندادن تصویر داد، این env را به الگوی مدل‌های URL-based گسترش دهید:

IMAGE_URL_RESPONSE_MODELS_REGEX_PATTERN=^(gpt-image|gapgpt/qwen-image)

اگر از IMAGE_SIZE=auto استفاده می‌کنید، فقط برای مدل‌هایی این کار را انجام دهید که واقعاً اندازه auto را پشتیبانی می‌کنند. برای شروع، 1024x1024 انتخاب کم‌ریسک‌تری است.

ویرایش تصویر

OpenWebUI قابلیت Image Editing هم دارد، اما پشتیبانی آن به مدل و endpoint بستگی دارد. اگر فقط تولید تصویر می‌خواهید، همین تنظیمات کافی است. اگر ویرایش تصویر می‌خواهید، در همان صفحه Images مقدارهای Image Edit Engine و Image Edit Model را فقط با مدلی تنظیم کنید که در گپ جی‌پی‌تی برای ویرایش تصویر تست شده یا در صفحه مدل‌ها به عنوان مدل مناسب ویرایش معرفی شده باشد.

۸. Speech-to-Text یا تبدیل گفتار به متن

برای STT، OpenWebUI می‌تواند به جای Whisper محلی از OpenAI-compatible API استفاده کند. مسیر گپ جی‌پی‌تی:

POST https://api.gapgpt.app/v1/audio/transcriptions

تنظیم از UI:

  1. وارد Admin Panel > Settings > Audio شوید.
  2. در بخش Speech-to-Text مقدار Engine را روی OpenAI بگذارید.
  3. مقدارها را وارد کنید:
API Base URL: https://api.gapgpt.app/v1
API Key: YOUR_GAPGPT_API_KEY
STT Model: gapgpt/whisper-1
Supported Content Types: خالی بگذارید یا audio/wav,audio/mpeg,audio/webm

تنظیم با env:

AUDIO_STT_ENGINE=openai
AUDIO_STT_OPENAI_API_BASE_URL=https://api.gapgpt.app/v1
AUDIO_STT_OPENAI_API_KEY=YOUR_GAPGPT_API_KEY
AUDIO_STT_MODEL=gapgpt/whisper-1

اگر فایل صوتی در OpenWebUI قبل از ارسال رد شد، مشکل ممکن است از پسوند فایل باشد، نه API. OpenWebUI برای STT فهرست پسوندهای مجاز دارد. فرمت‌های کم‌ریسک برای شروع: mp3، wav، m4a و webm.

۹. Text-to-Speech یا تبدیل متن به گفتار

برای TTS، OpenWebUI باید بتواند مدل را از مسیر OpenAI-compatible زیر صدا بزند:

POST https://api.gapgpt.app/v1/audio/speech

تنظیم از UI:

  1. وارد Admin Panel > Settings > Audio شوید.
  2. در بخش Text-to-Speech مقدار Engine را روی OpenAI بگذارید.
  3. مقدارها را وارد کنید:
API Base URL: https://api.gapgpt.app/v1
API Key: YOUR_GAPGPT_API_KEY
TTS Model: نام مدل TTS سازگار با /v1/audio/speech
TTS Voice: alloy

تنظیم با env:

AUDIO_TTS_ENGINE=openai
AUDIO_TTS_OPENAI_API_BASE_URL=https://api.gapgpt.app/v1
AUDIO_TTS_OPENAI_API_KEY=YOUR_GAPGPT_API_KEY
AUDIO_TTS_MODEL=YOUR_TTS_MODEL
AUDIO_TTS_VOICE=alloy

قبل از تنظیم TTS در OpenWebUI، مدل TTS را در صفحه مدل‌ها و قیمت‌ها بررسی کنید. اگر یک مدل TTS در نمونه کدهای گپ جی‌پی‌تی با API بومی Gemini یا مسیر models/...:generateContent معرفی شده باشد، ممکن است برای OpenWebUI TTS مناسب نباشد، چون OpenWebUI در حالت OpenAI TTS مسیر /audio/speech را صدا می‌زند. برای OpenWebUI مدلی را انتخاب کنید که با /v1/audio/speech تست شده باشد.

برای تست، بعد از دریافت پاسخ از یک مدل متنی، روی آیکن بلندگو کنار پیام Assistant کلیک کنید. اگر صدا پخش نشد، Base URL، API Key، مدل، voice و دسترسی مرورگر به پخش صدا را بررسی کنید.

۱۰. ویدئو، موسیقی و قابلیت‌های غیر استاندارد

OpenWebUI اتصال OpenAI-compatible را برای چت، مدل‌ها، embedding، تصویر، STT و TTS به صورت آماده پشتیبانی می‌کند. اما ویدئو، موسیقی یا endpointهای اختصاصی دیگر معمولاً در UI استاندارد OpenWebUI دکمه و جریان آماده ندارند.

اگر می‌خواهید از مدل‌های ویدئو یا موسیقی گپ جی‌پی‌تی داخل OpenWebUI استفاده کنید، سه مسیر امن‌تر دارید:

  1. یک Tool / Function در OpenWebUI بسازید که با HTTP به endpoint مورد نظر گپ جی‌پی‌تی درخواست بزند.
  2. از یک workflow بیرونی مثل n8n استفاده کنید و نتیجه را به OpenWebUI یا کاربر برگردانید.
  3. اگر نسخه OpenWebUI شما برای آن modality افزونه یا Action آماده دارد، آن را جداگانه تست کنید.

برای این قابلیت‌ها صرفاً اضافه کردن Provider در Connections کافی نیست.

۱۱. چک‌لیست تست قبل از استفاده تیمی

قبل از اینکه OpenWebUI را برای چند کاربر باز کنید، این موارد را تست کنید:

۱۲. خطایابی

مدل‌ها در OpenWebUI دیده نمی‌شوند

خطای 401 یا 403 می‌گیرم

چت کار می‌کند اما تصویر یا صدا کار نمی‌کند

اتصال چت فقط بخش Connections را تنظیم می‌کند. تصویر و صدا تنظیمات جدا دارند:

تصویر تولید می‌شود ولی در OpenWebUI نمایش داده نمی‌شود

STT از مرورگر استفاده می‌کند و به گپ جی‌پی‌تی نمی‌رسد

در OpenWebUI دو نوع STT وجود دارد: تنظیم User-level مثل Web API که از قابلیت مرورگر استفاده می‌کند، و تنظیم Admin-level که backend را به OpenAI-compatible STT وصل می‌کند. برای استفاده از گپ جی‌پی‌تی باید Admin Panel > Settings > Audio را تنظیم کنید و AUDIO_STT_ENGINE=openai باشد.

۱۳. تست مستقیم با curl

اگر نمی‌دانید مشکل از OpenWebUI است یا API، بیرون از OpenWebUI تست کنید.

مدل‌ها:

curl https://api.gapgpt.app/v1/models \
  -H "Authorization: Bearer YOUR_GAPGPT_API_KEY"

چت:

curl https://api.gapgpt.app/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GAPGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "سلام!"}]
  }'

تصویر:

curl https://api.gapgpt.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_GAPGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo on a white background",
    "size": "1024x1024"
  }'

تبدیل گفتار به متن:

curl https://api.gapgpt.app/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_GAPGPT_API_KEY" \
  -F model="gapgpt/whisper-1" \
  -F file="@audio.mp3"

تبدیل متن به گفتار:

curl https://api.gapgpt.app/v1/audio/speech \
  -H "Authorization: Bearer YOUR_GAPGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_TTS_MODEL",
    "voice": "alloy",
    "input": "سلام! این یک تست صداست."
  }' \
  --output speech.mp3

۱۴. منابع بیشتر

در صورت بروز مشکل، ابتدا تست‌های curl بخش قبل را اجرا کنید. اگر curl موفق بود ولی OpenWebUI خطا داشت، مشکل معمولاً در مسیر تنظیمات جداگانه OpenWebUI، Model IDs Filter، یا تنظیمات Image/Audio/Documents است.