Responses API | AiFO Docs

نمای کلی

POST /v1/responses یک endpoint سازگار با OpenAI Responses است. با تغییر base URL، API Key و model در OpenAI SDK می‌توانید از AiFO استفاده کنید. Phase 2.4 از providerهای OpenAI و OpenRouter پشتیبانی می‌کند، اما ادعای parity کامل با OpenAI Responses را ندارد.

ورودی متنی (string) و structured با input_text
input_image با image_url (https یا data URL)
input_file.file_id متعلق به AiFO (file_…) — نه شناسهٔ provider با پیشوند file-
streaming با eventهای بومی Responses
function tools و hosted tools: web_search / web_search_preview؛ روی OpenRouter همچنین web_fetch
include، max_tool_calls و parallel_tool_calls برای کنترل هزینه و citations
مدل‌های بدون responses.endpoint=supported → unsupported_endpoint

Web search

برای جستجوی وب، tool میزبانی‌شدهٔ web_search را در tools بفرستید. AiFO خودش موتور search اجرا نمی‌کند؛ درخواست به OpenAI یا OpenRouter proxy می‌شود. روی OpenRouter، type به openrouter:web_search بازنویسی می‌شود. برای دیدن منابع، include را با web_search_call.action.sources ست کنید. هزینهٔ چندبارهٔ search ممکن است بالا برود — max_tool_calls و search_context_size: low|medium را در نظر بگیرید.

curl https://api.aifoapp.ir/v1/responses \
  -H "Authorization: Bearer aifo_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "آخرین قیمت بیت‌کوین چقدر است؟",
    "tools": [{ "type": "web_search", "search_context_size": "medium" }],
    "include": ["web_search_call.action.sources"],
    "max_tool_calls": 3
  }'

from openai import OpenAI

client = OpenAI(base_url="https://api.aifoapp.ir/v1", api_key="aifo_sk_live_YOUR_API_KEY")
resp = client.responses.create(
    model="gpt-4o-mini",
    input="آخرین قیمت بیت‌کوین چقدر است؟",
    tools=[{"type": "web_search", "search_context_size": "medium"}],
    include=["web_search_call.action.sources"],
    max_tool_calls=3,
)
print(resp.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.aifoapp.ir/v1",
  apiKey: "aifo_sk_live_YOUR_API_KEY",
});

const resp = await client.responses.create({
  model: "gpt-4o-mini",
  input: "آخرین قیمت بیت‌کوین چقدر است؟",
  tools: [{ type: "web_search", search_context_size: "medium" }],
  include: ["web_search_call.action.sources"],
  max_tool_calls: 3,
});
console.log(resp.output_text);

نمونهٔ OpenAI

curl https://api.aifoapp.ir/v1/responses \
  -H "Authorization: Bearer aifo_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "سلام! یک جمله کوتاه بنویس."
  }'

from openai import OpenAI

client = OpenAI(base_url="https://api.aifoapp.ir/v1", api_key="aifo_sk_live_YOUR_API_KEY")
resp = client.responses.create(
    model="gpt-4o-mini",
    input="سلام! یک جمله کوتاه بنویس.",
)
print(resp.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.aifoapp.ir/v1",
  apiKey: "aifo_sk_live_YOUR_API_KEY",
});

const resp = await client.responses.create({
  model: "gpt-4o-mini",
  input: "سلام! یک جمله کوتاه بنویس.",
});
console.log(resp.output_text);

const OpenAI = require("openai");

const client = new OpenAI({
  baseURL: "https://api.aifoapp.ir/v1",
  apiKey: "aifo_sk_live_YOUR_API_KEY",
});

async function main() {
  const resp = await client.responses.create({
    model: "gpt-4o-mini",
    input: "سلام! یک جمله کوتاه بنویس.",
  });
  console.log(resp.output_text);
}
main();

نمونهٔ OpenRouter (از طریق AiFO)

مدل‌هایی مثل openai/gpt-4o-mini روی OpenRouter وقتی responses.endpoint در پروفایل مؤثر supported باشد، از همان /v1/responses AiFO قابل فراخوانی‌اند. مدل‌های بدون این قابلیت با unsupported_endpoint رد می‌شوند.

curl https://api.aifoapp.ir/v1/responses \
  -H "Authorization: Bearer aifo_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "input": "Reply with exactly: ok"
  }'

from openai import OpenAI

client = OpenAI(base_url="https://api.aifoapp.ir/v1", api_key="aifo_sk_live_YOUR_API_KEY")
resp = client.responses.create(
    model="openai/gpt-4o-mini",
    input="Reply with exactly: ok",
)
print(resp.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.aifoapp.ir/v1",
  apiKey: "aifo_sk_live_YOUR_API_KEY",
});

const resp = await client.responses.create({
  model: "openai/gpt-4o-mini",
  input: "Reply with exactly: ok",
});
console.log(resp.output_text);

const OpenAI = require("openai");

const client = new OpenAI({
  baseURL: "https://api.aifoapp.ir/v1",
  apiKey: "aifo_sk_live_YOUR_API_KEY",
});

async function main() {
  const stream = await client.responses.create({
    model: "openai/gpt-4o-mini",
    input: "Say hi",
    stream: true,
  });
  for await (const event of stream) {
    console.log(event.type);
  }
}
main();

فایل AiFO در Responses

پس از آپلود با POST /v1/files، شناسهٔ file_… را در input_file بفرستید. Gateway قبل از wallet reserve فایل را از MinIO خصوصی می‌خواند و به صورت inline file_data برای OpenAI یا OpenRouter ارسال می‌کند. شناسهٔ AiFO هرگز خام به provider نمی‌رسد.

{
  "model": "openai/gpt-4o-mini",
  "input": [{
    "role": "user",
    "content": [
      { "type": "input_text", "text": "خلاصه این PDF را بگو" },
      { "type": "input_file", "file_id": "file_..." }
    ]
  }]
}

Streaming

با stream:true رویدادهای بومی Responses (مثل response.created، response.output_text.delta، response.completed) به‌صورت SSE فوروارد می‌شوند. درخواست نامعتبر قبل از reserve و قبل از ارسال headerهای SSE رد می‌شود.

محدودیت‌های Phase 2.4

OpenAI + OpenRouter (beta، model-gated)؛ بدون claim parity کامل
stateless: store باید false/omit باشد
بدون previous_response_id و بدون retrieve/delete response
بدون MCP، computer_use، code_interpreter، file_search/vector store، یا persistence مکالمه
بدون آپلود به OpenAI Files API یا provider file mapping