یکپارچه‌سازی — ابزارهای کدنویسی، SDKها و اپ‌های چت

هر ابزاری که «OpenAI-compatible» است با یوتاپن کار می‌کند و سه مقدار می‌خواهد: آدرس https://api.uttapen.ir/v1، کلید sk-up-… و شناسهٔ مدل به شکل provider/model از فهرست مدل‌ها. این صفحه نقشهٔ کلی است؛ برای agentهای کدنویسی، هر کدام راهنمای جداگانهٔ خودش را دارد.

ابزارهای کدنویسی

سه قاعده برای همهٔ agentها:

1. سقف خروجی را خودت تعیین کن. یوتاپن پیش از ارسال، هزینهٔ کل max_tokens را رزرو می‌کند و بعد فقط مصرف واقعی را کم می‌کند (قیمت‌گذاری). بعضی agentها اگر ندانند، ۳۲٬۰۰۰ توکن می‌فرستند و چون هم‌زمان چند درخواست دارند، رزروها جمع می‌شود و با موجودی سالم هم 402 می‌گیری.
2. یک مدل ارزان برای کارهای جانبی بگذار. عنوان گفتگو، پیام commit و خلاصه‌سازی نباید روی مدل گران‌قیمت بروند.
3. برای هر ابزار یک کلید جدا با سقف ماهانه بساز تا مصرف هرکدام در داشبورد ← مصرف جدا دیده شود (کلیدها).

LangChain (Python)

pip install langchain-openai

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="openai/gpt-5-mini",
    base_url="https://api.uttapen.ir/v1",
    api_key="sk-up-...",
    max_tokens=500,
)
print(llm.invoke("سه مزیت Postgres را بگو.").content)

for chunk in llm.stream("یک جملهٔ انگیزشی کوتاه"):
    print(chunk.content, end="", flush=True)

Tool calling با llm.bind_tools([...]) و خروجی ساخت‌یافته با llm.with_structured_output(Schema) همان‌طور که با OpenAI کار می‌کند، اینجا هم کار می‌کند. در LangChain.js همین فیلدها روی new ChatOpenAI({ model, apiKey, configuration: { baseURL } }) هستند. اگر سراغ embeddings رفتی، OpenAIEmbeddings به check_embedding_ctx_length=False نیاز دارد (وگرنه متن را با توکن‌شمار محلی OpenAI می‌شکند) و شناسهٔ مدل باید در فهرست مدل‌ها موجود باشد.

LlamaIndex (Python)

pip install llama-index-llms-openai-like

from llama_index.llms.openai_like import OpenAILike
from llama_index.core.llms import ChatMessage

llm = OpenAILike(
    model="openai/gpt-5-mini",
    api_base="https://api.uttapen.ir/v1",
    api_key="sk-up-...",
    is_chat_model=True,
    is_function_calling_model=True,
    context_window=128000,
)
print(llm.complete("سه مزیت Postgres را بگو.").text)
for chunk in llm.stream_chat([ChatMessage(role="user", content="سلام")]):
    print(chunk.delta, end="", flush=True)

از OpenAILike استفاده کن نه OpenAI؛ کلاس دوم شناسهٔ مدل را با فهرست ثابت مدل‌های OpenAI چک می‌کند و openai/… را رد می‌کند. is_chat_model=True الزامی است.

Vercel AI SDK (Node و Next.js)

npm install ai @ai-sdk/openai-compatible

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText, streamText } from "ai";

const uttapen = createOpenAICompatible({
  name: "uttapen",
  baseURL: "https://api.uttapen.ir/v1",
  apiKey: process.env.UTTAPEN_API_KEY,
  includeUsage: true,
});

const { text, usage } = await generateText({
  model: uttapen("openai/gpt-5-mini"),
  prompt: "سه مزیت Postgres را بگو.",
  maxOutputTokens: 300,
});

const result = streamText({ model: uttapen("anthropic/claude-sonnet-5"), prompt: "سلام" });
for await (const delta of result.textStream) process.stdout.write(delta);

در route handler Next.js، result.toUIMessageStreamResponse() (یا toTextStreamResponse()) را برگردان و در کلاینت از useChat استفاده کن؛ کلید فقط در سرور می‌ماند. برای reasoning و فیلدهای اختصاصی از providerOptions: { uttapen: { reasoning: { effort: "low" } } } استفاده کن. @ai-sdk/openai (پکیج اختصاصی OpenAI) هم baseURL می‌گیرد ولی بعضی قابلیت‌هایش روی Responses API بنا شده و با یوتاپن جواب نمی‌دهد؛ openai-compatible انتخاب امن است.

اپ‌های چت و اتوماسیون

نام دقیق فیلدها در رابط این اپ‌ها بین نسخه‌ها عوض می‌شود؛ اگر عنوانی را که نوشته‌ایم ندیدی، دنبال نزدیک‌ترین معادلش در همان صفحه بگرد.

Open WebUI — Settings ← Admin ← Connections ← Manage OpenAI API Connections ← افزودن اتصال. آدرس https://api.uttapen.ir/v1 و کلید. اگر فیلد Model IDs را خالی بگذاری فهرست را از /v1/models می‌گیرد و هر ۴۰۰+ مدل می‌آید؛ چند شناسه که واقعاً لازم داری بنویس تا فهرست کوتاه شود. در Settings ← Admin ← Interface گزینهٔ External Task Model را روی مدل ارزان بگذار، وگرنه عنوان‌گذاری و تولید تگ روی مدل اصلی می‌رود. با Docker همین دو مقدار را می‌توانی با OPENAI_API_BASE_URL و OPENAI_API_KEY بدهی (فقط در اولین اجرا خوانده می‌شوند).

LibreChat — در librechat.yaml:

endpoints:
  custom:
    - name: "uttapen"
      apiKey: "${UTTAPEN_API_KEY}"
      baseURL: "https://api.uttapen.ir/v1"
      models:
        default: ["openai/gpt-5-mini"]
        fetch: true
      titleConvo: true
      titleModel: "openai/gpt-5-nano"
      modelDisplayLabel: "uttapen"

titleModel را حتماً بنویس؛ پیش‌فرضش مدلی است که در فهرست ما وجود ندارد و عنوان‌سازی 404 می‌گیرد. نام endpoint را هم مثل نام‌های داخلی (openAI و مانند آن) نگذار.

LobeHub (LobeChat) — در تنظیمات، AI Providers ← ساخت provider سفارشی با Request Format روی OpenAI، آدرس https://api.uttapen.ir/v1 و کلید. اگر به‌جایش provider داخلی OpenAI را با متغیر OPENAI_PROXY_URL عوض کنی، باید سوییچ Responses آن provider را خاموش کنی، چون به‌صورت پیش‌فرض روشن است. برای عنوان خودکار، Settings ← Service Model مدل ارزان انتخاب کن.

Chatbox — Settings ← Model Provider ← Add، در فیلد API Mode گزینهٔ OpenAI API Compatible (نه Responses). API Host را https://api.uttapen.ir/v1 بگذار و API Path را خالی بگذار تا خودش /chat/completions را اضافه کند. دکمهٔ Fetch فهرست مدل‌ها را می‌آورد. در Default Models مدل نام‌گذاری گفتگو را ارزان انتخاب کن.

Jan — Settings ← Model Providers ← Add Provider، قالب API را OpenAI-compatible بگذار، Base URL را با /v1 بنویس و کلید را وارد کن؛ بدون /v1 درخواست‌ها 404 می‌شوند. بعد از ذخیره، مدل‌ها را از /v1/models می‌آورد. Jan قابلیت‌های مدل سفارشی (ابزار، تصویر) را تشخیص نمی‌دهد.

AnythingLLM — LLM Provider را روی Generic OpenAI بگذار: Base URL با /v1، کلید، نام مدل، و حتماً دو فیلد عددی را پر کن؛ پیش‌فرض‌های context (۴۰۹۶) و Max Tokens (۱۰۲۴) خیلی کوچک‌اند و جواب‌ها را نصفه می‌کنند. معادل متغیرهای محیطی: LLM_PROVIDER='generic-openai'، GENERIC_OPEN_AI_BASE_PATH، GENERIC_OPEN_AI_API_KEY، GENERIC_OPEN_AI_MODEL_PREF.

n8n — در credential نوع OpenAI، فیلد Base URL را https://api.uttapen.ir/v1 بگذار و کلید sk-up-… را وارد کن. بعد در نود OpenAI Chat Model گزینهٔ «Use Responses API» را خاموش کن؛ در نسخه‌های اخیر پیش‌فرضش روشن است و یوتاپن آن مسیر را ندارد. نود عمومی OpenAI (عملیات Message a Model) همیشه از همان مسیر استفاده می‌کند و با ما کار نمی‌کند؛ از نود Chat Model استفاده کن. شناسه‌هایی که نامشان codex یا -pro دارد را هم در این نود استفاده نکن؛ کتابخانهٔ زیرین برای آن‌ها خودش مسیر Responses را انتخاب می‌کند.

Dify — Model Provider ← نصب OpenAI-API-compatible ← Add Model. Model Name شناسهٔ ما، API Base URL آدرس با /v1، Completion mode روی Chat. دو فیلد «model context size» و «upper bound for max tokens» پیش‌فرض ۴۰۹۶ دارند؛ اصلاحشان کن. برای agent و ابزارها، Function Call Type را روی Tool Call بگذار (پیش‌فرضش Not Support است). Dify فهرست مدل را نمی‌خواند؛ هر مدل را دستی اضافه کن. مدل پیش‌فرض کارهای سیستمی هم در Default Models تنظیم می‌شود.

Flowise — از نود OpenAI Custom Model استفاده کن: Model Name را دستی بنویس و در Additional Parameters فیلد Base Path را https://api.uttapen.ir/v1 بگذار؛ credential همان نوع OpenAI API است. نود معمولی ChatOpenAI فهرست مدل خودش را دارد و شناسه‌های ما در آن نیست.

قاعده‌های مشترک

• اگر ابزار مسیر /v1 را خودش اضافه می‌کند و 404 می‌گیری، آدرس را بدون /v1 بده. با curl https://api.uttapen.ir/v1/models می‌توانی سریع بفهمی کدام شکل درست است.
• هر جا گزینهٔ Responses API (یا «OpenAI Responses») دیدی، خاموشش کن؛ یوتاپن فقط Chat Completions، Completions و Embeddings دارد (مهاجرت).
• اگر ابزار فهرست مدل را از GET /v1/models می‌گیرد، همه‌چیز خودکار است؛ اگر نه، شناسه را دقیق و با حروف کوچک وارد کن.
• هر ابزاری که درخواست پس‌زمینه می‌فرستد (عنوان، تگ، خلاصه) یک مدل ارزان جدا می‌خواهد، وگرنه هزینهٔ پنهان می‌سازد.
• کدهای خطا و معنی هرکدام در خطاها است.