مستندات فنی

کلید خود را در هدر Authorization: Bearer zpr-v1-... ارسال کنید. تعیین سقف مصرف دلاری، محدودیت نرخ درخواست (RPM) و لیست IP مجاز در /app/keys

شناسه‌ی استاندارد هر مدل (مانند openai/gpt-4o یا anthropic/claude-3.7-sonnet) را ارسال کنید. در صورت بروز خطای 5xx یا محدودیت نرخ پیش از شروع استریم، درگاه به صورت خودکار به ارائه‌دهنده‌ی سالم بعدی سوییچ می‌کند.

با ارسال stream: true پاسخ را به صورت رویدادهای SSE دریافت کنید. برای دریافت مصرف توکن و هزینه‌ی دقیق دلاری در انتهای استریم، stream_options.include_usage = true را فعال کنید.

const stream = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  stream: true,
  stream_options: { include_usage: true },
  messages: [{ role: 'user', content: 'Stream a haiku about distributed systems.' }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
  if (chunk.usage) {
    console.log('\nTokens & exact USD cost:', chunk.usage);
  }
}

مدل‌های دارای قابلیت tools از ساختار استاندارد tools و tool_choice در OpenAI برای فراخوانی توابع پشتیبانی می‌کنند.

const response = await client.chat.completions.create({
  model: 'openai/gpt-6.1-sol-pro',
  messages: [{ role: 'user', content: 'What is the exchange rate for USD to EUR?' }],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_fx_rate',
        description: 'Get live market exchange rate for a currency pair',
        parameters: {
          type: 'object',
          properties: {
            base: { type: 'string', enum: ['USD'] },
            quote: { type: 'string', enum: ['EUR', 'GBP', 'CHF'] },
          },
          required: ['base', 'quote'],
        },
      },
    },
  ],
  tool_choice: 'auto',
});

برای دریافت خروجی منطبق بر اسکیما، پارامتر response_format را با نوع json_schema یا json_object ارسال کنید.

const response = await client.chat.completions.create({
  model: 'google/gemini-2.5-pro',
  messages: [{ role: 'user', content: 'Extract invoice fields from: Invoice #904 for $25.00' }],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'invoice',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          invoiceNumber: { type: 'string' },
          amountUsd: { type: 'number' },
        },
        required: ['invoiceNumber', 'amountUsd'],
        additionalProperties: false,
      },
    },
  },
});

در مدل‌های استدلالگر (مانند deepseek/deepseek-r1 یا claude-3.7-sonnet) می‌توانید عمق تفکر را با reasoning_effort ('low' | 'medium' | 'high') تنظیم کنید.

const response = await client.chat.completions.create({
  model: 'deepseek/deepseek-r1',
  reasoning_effort: 'high',
  messages: [{ role: 'user', content: 'Prove that the square root of 2 is irrational.' }],
});

تمامی پاسخ‌ها شامل هدرهای x-ratelimit-limit، x-ratelimit-remaining و x-ratelimit-reset هستند و در صورت عبور از سقف، کد 429 به همراه هدر Retry-After بازگردانده می‌شود.

پیش از ارسال درخواست به منبع، حداکثر هزینه‌ی احتمالی به صورت اتمی رزرو شده و پس از پایان پاسخ، هزینه‌ی دقیق نانودلار تسویه می‌شود. موجودی و هزینه‌ی هر درخواست از طریق API قابل استعلام است.

# Check API key limits & remaining budget
curl https://api.zopyr.com/v1/key \
  -H "Authorization: Bearer $ZOPYR_API_KEY"

# Check wallet balance & total usage
curl https://api.zopyr.com/v1/credits \
  -H "Authorization: Bearer $ZOPYR_API_KEY"

# Inspect exact token count, latency & settled cost for a generation
curl "https://api.zopyr.com/v1/generation?id=gen-0192a3b4..." \
  -H "Authorization: Bearer $ZOPYR_API_KEY"

به صورت پیش‌فرض، متن پرامپت و پاسخ هرگز ذخیره نمی‌شود و تنها متادیتای مصرف ثبت می‌گردد. لاگ محتوا صرفاً در صورت فعال‌سازی صریح روی کلید با رمزنگاری AES-256-GCM ذخیره می‌شود.

گیت‌وی زوپیر علاوه بر /v1/chat/completions، به صورت بومی از استاندارد جدید OpenAI Responses API، پروتکل Anthropic Messages (سازگار با Claude Code)، ساخت بردارهای Embeddings، آپلود رمزنگاری‌شدهٔ فایل‌ها و ارتباط بلادرنگ WebSocket پشتیبانی می‌کند.

const res = await fetch('https://api.zopyr.com/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZOPYR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-6.1-sol-pro',
    instructions: 'Return concise engineering guidance.',
    input: 'Explain distributed circuit breaking in 3 bullets.',
    max_output_tokens: 512,
  }),
});
const data = await res.json();
console.log(data.output_text, data.usage);