OpenAI-compatible · /v1/chat/completions

API سازگار با OpenAI برای مدل‌های زبانی

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

آدرس پایه (base_url)

https://api.noqte.ai/v1

اولین درخواست · POST /v1/chat/completions

Python · openai SDK
# pip install openai
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.noqte.ai/v1",
    api_key=os.environ["NOQTE_API_KEY"],
)

reply = client.chat.completions.create(
    model="noqte-1.2",
    messages=[{"role": "user", "content": "سلام! یک جمله دربارهٔ تهران بنویس."}],
    max_tokens=300,
)
print(reply.choices[0].message.content)
احراز هویت
Bearer
پرداخت
کردیت کیف پول
stream و ابزارها
دارد
پیش‌نیاز اشتراک پرو
ندارد

01 · Quick start

شروع سریع در سه قدم

کلید را فقط سمت سرور و در متغیر محیطی (مثلاً NOQTE_API_KEY) نگه دارید و هرگز در کد سمت مرورگر یا اپ موبایل نگذارید.

  1. 01

    کردیت بخرید

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

  2. 02

    کلید بسازید

    در پنل، صفحهٔ «API کردیت»، یک کلید بسازید. کلید فقط یک‌بار نمایش داده می‌شود؛ آن را در متغیر محیطی نگه دارید.

  3. 03

    آدرس پایه را عوض کنید

    در کتابخانه یا ابزار خود base_url را آدرس زیر و api_key را کلید نقطه بگذارید. بقیهٔ کد همان کد OpenAI است.

cURL
curl https://api.noqte.ai/v1/chat/completions \
  -H "Authorization: Bearer $NOQTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "noqte-1.2",
    "messages": [{"role": "user", "content": "سلام! یک جمله دربارهٔ تهران بنویس."}],
    "max_tokens": 300
  }'
Python
# pip install openai
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.noqte.ai/v1",
    api_key=os.environ["NOQTE_API_KEY"],
)

reply = client.chat.completions.create(
    model="noqte-1.2",
    messages=[{"role": "user", "content": "سلام! یک جمله دربارهٔ تهران بنویس."}],
    max_tokens=300,
)
print(reply.choices[0].message.content)

نمونهٔ پاسخ

200 OK · application/json
{
  "id": "nq_e13651caa3c4c20201ca1b5b",
  "object": "chat.completion",
  "created": 1794731582,
  "model": "noqte-1.2",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "تهران پایتخت ایران است و شهری پرجنب‌وجوش با تاریخ و فرهنگی غنی است."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 37,
    "completion_tokens": 21,
    "total_tokens": 58
  }
}

02 · Authentication

احراز هویت و کلید

کلید با پیشوند sk-noqte- در صفحهٔ «API و اتصال ابزارها» پنل ساخته می‌شود و فقط یک‌بار نمایش داده می‌شود. آن را در هدر Authorization به شکل Bearer sk-noqte-… بفرستید؛ هدر x-api-key هم پذیرفته می‌شود.

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

HTTP
POST /v1/chat/completions HTTP/1.1
Host: api.noqte.ai
Authorization: Bearer sk-noqte-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

03 · Endpoints

مسیرهای API

همهٔ مسیرها زیر آدرس پایه هستند و با همان کلید کار می‌کنند. شناسهٔ مدل‌ها را دستی ننویسید؛ از GET /v1/models بخوانید.

POST/v1/chat/completions

ارسال گفتگو و گرفتن پاسخ؛ معمولی یا stream.

GET/v1/models

فهرست مدل‌هایی که این کلید می‌تواند صدا بزند. مدل‌هایی که در endpoints آن‌ها chat/completions آمده با این API کار می‌کنند.

GET/v1/usage

موجودی کردیت کیف پول در فیلد balance_credits.

cURL · GET /v1/models
curl https://api.noqte.ai/v1/models \
  -H "Authorization: Bearer $NOQTE_API_KEY"

04 · Features

امکانات پشتیبانی‌شده

بدنهٔ درخواست و پاسخ همان قالب Chat Completions در OpenAI است.

01

stream

با stream: true پاسخ به‌صورت رویدادهای data: می‌آید و با data: [DONE] تمام می‌شود. اگر stream_options.include_usage را true بگذارید، مصرف توکن در آخرین تکه برمی‌گردد.

02

فراخوانی ابزار

tools و tool_choice مثل OpenAI؛ پاسخ مدل tool_calls دارد و نتیجهٔ ابزار را با پیامی با role: "tool" و همان tool_call_id برمی‌گردانید. در stream هم کار می‌کند.

03

ورودی تصویر

در content پیام، بخشی با type: "image_url" بفرستید؛ لینک تصویر یا data URL (base64) هر دو پذیرفته می‌شوند.

04

سقف خروجی

max_tokens یا max_completion_tokens. اگر کردیت کیف پول برای سقف درخواستی کافی نباشد، پاسخ کوتاه‌تر می‌شود یا خطای 402 می‌گیرید.

05

نام مدل در پاسخ

فیلد model در پاسخ و در هر تکهٔ stream همان شناسه‌ای است که فرستاده‌اید.

cURL · stream
curl -N https://api.noqte.ai/v1/chat/completions \
  -H "Authorization: Bearer $NOQTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "noqte-1.2",
    "messages": [{"role": "user", "content": "از ۱ تا ۵ بشمار"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'
Python · stream
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.noqte.ai/v1", api_key=os.environ["NOQTE_API_KEY"])

stream = client.chat.completions.create(
    model="noqte-1.2",
    messages=[{"role": "user", "content": "از ۱ تا ۵ بشمار"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\ntokens:", chunk.usage.total_tokens)
Python · tools
import json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.noqte.ai/v1", api_key=os.environ["NOQTE_API_KEY"])
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    },
}]
messages = [{"role": "user", "content": "هوای تهران چطور است؟"}]

first = client.chat.completions.create(model="noqte-1.2", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
print(call.function.name, json.loads(call.function.arguments))

messages += [
    first.choices[0].message.model_dump(exclude_none=True),
    {"role": "tool", "tool_call_id": call.id, "content": "آفتابی، ۲۱ درجه"},
]
final = client.chat.completions.create(model="noqte-1.2", messages=messages, tools=tools)
print(final.choices[0].message.content)

05 · Billing

هزینه و موجودی

موجودی را از داخل برنامه با GET /v1/usage بخوانید.

  • هزینهٔ هر درخواست بر اساس توکن‌های ورودی و خروجی واقعی همان درخواست و با تعرفهٔ همان مدل از کردیت کیف پول کم می‌شود. تعرفهٔ هر مدل در صفحهٔ «API کردیت» پنل آمده است.
  • درخواستی که با خطا رد شود (مثلاً کلید نامعتبر، مدل ناموجود یا messages نادرست) هزینه‌ای ندارد.
  • اگر اتصال stream را وسط کار ببندید، فقط هزینهٔ بخشی که تا آن لحظه تولید شده حساب می‌شود.
  • کردیت رایگان روزانهٔ حساب در API مصرف نمی‌شود؛ فقط موجودی کیف پول.
  • اگر موجودی کافی نباشد، پاسخ 402 با code: insufficient_credits می‌گیرید. اگر کردیت وسط stream تمام شود، پاسخ با یک پیام خطا متوقف می‌شود.
  • برای هر کلید می‌توانید سقف کردیت روزانه و سقف کل بگذارید. وقتی کلید به سقفش برسد، پاسخ 429 با code: credit_limit_exceeded می‌گیرید.

06 · Idempotency

تکرار امن درخواست

  • هدر Idempotency-Key اختیاری است (حداکثر ۲۴۰ نویسه). اگر در timeout یا قطع اتصال همان شناسه را با همان بدنه دوباره بفرستید، همان پاسخ قبلی برمی‌گردد و هزینهٔ دوباره ندارد.
  • همان شناسه با بدنهٔ متفاوت خطای 409 با code: idempotency_conflict می‌دهد.
  • اگر درخواست اول هنوز در حال اجراست، تکرار آن 409 با code: request_already_admitted می‌گیرد؛ کمی بعد دوباره بفرستید.
  • برای هر درخواست واقعاً جدید، شناسهٔ تازه بسازید.

07 · Errors

خطاها

خطاها به همان شکل OpenAI برمی‌گردند، پس SDK رسمی آن‌ها را مثل خطای OpenAI می‌خواند.

404 · application/json
{
  "error": {
    "message": "The model is not enabled.",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}
  • 400invalid_request_error
    invalid_messages

    بدنه نامعتبر است؛ مثلاً messages آرایه نیست یا JSON درست نیست.

  • 401authentication_error
    —

    کلید فرستاده نشده یا معتبر نیست.

  • 402insufficient_quota
    insufficient_credits

    کردیت کیف پول برای این درخواست کافی نیست.

  • 403permission_error
    model_not_allowed · scope_not_allowed · ip_not_allowed

    این کلید به این مدل یا عملیات دسترسی ندارد، یا درخواست از IP مجاز کلید نیامده است.

  • 403permission_error
    api_credits_required

    حساب کردیت خریداری‌شده ندارد.

  • 404invalid_request_error
    model_not_found

    شناسهٔ مدل فعال نیست؛ شناسه را از GET /v1/models بخوانید.

  • 409invalid_request_error
    idempotency_conflict

    همان Idempotency-Key با بدنهٔ دیگری استفاده شده است.

  • 429rate_limit_error
    rate_limit_exceeded · concurrency_exceeded

    تعداد درخواست در دقیقه یا درخواست‌های هم‌زمان زیاد است؛ بعد از Retry-After دوباره بفرستید.

  • 429rate_limit_error
    credit_limit_exceeded

    کلید به سقف کردیتی که برایش گذاشته‌اید رسیده است.

08 · Limits

محدودیت‌ها

درخواست در دقیقه
۶۰ برای هر حساب
درخواست هم‌زمان
۸ برای هر حساب
سقف کردیت کلید
روزانه و کل، اختیاری
محدودیت کلید
مدل‌ها و IPهای مجاز، اختیاری

این مقادیر پیش‌فرض حساب‌های عادی است. وقتی به سقف درخواست برسید، پاسخ 429 همراه هدر Retry-After (به ثانیه) می‌آید.

09 · FAQ

پرسش‌های پرتکرار

آیا برای این API اشتراک پرو لازم است؟

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

با کردیت رایگان روزانه هم می‌شود از API استفاده کرد؟

خیر. کردیت رایگان روزانه فقط برای چت داخل نقطه است. برای ساخت کلید و فراخوانی API باید کردیت بخرید.

کدام مدل‌ها را می‌توانم صدا بزنم؟

فهرست زندهٔ مدل‌ها را از GET /v1/models بخوانید. هر مدلی که در فیلد endpoints آن chat/completions آمده با این API کار می‌کند. همین فهرست با تعرفه‌ها در صفحهٔ «API کردیت» پنل هم هست.

با کدام کتابخانه‌ها و ابزارها کار می‌کند؟

با هر کتابخانه یا ابزاری که آدرس پایهٔ OpenAI را قابل تنظیم می‌کند؛ مثل کتابخانهٔ رسمی openai در Python و Node.js. کافی است base_url را آدرس پایهٔ نقطه (با /v1 در انتها) و api_key را کلید sk-noqte بگذارید.

خطایم شکل خطای OpenAI را دارد؟

بله. بدنهٔ خطا به شکل {"error": {"message", "type", "param", "code"}} است، پس SDK رسمی آن را مثل خطای OpenAI می‌خواند.

موجودی کردیتم را چطور از داخل برنامه بخوانم؟

با GET /v1/usage و همان کلید. پاسخ شامل balance_credits است.

کلید بسازید و اولین درخواست را بفرستید

کلید کردیت در چند ثانیه ساخته می‌شود، سقف کردیت آن قابل تنظیم است و هزینه از کیف پول همان حساب کم می‌شود.

ساخت کلید API