OpenAI-compatible · /v1/chat/completions
API سازگار با OpenAI برای مدلهای زبانی
اگر کردیت نقطه خریدهاید، با کلید sk-noqte میتوانید مدلهای زبانی نقطه را از هر برنامه، کتابخانه یا ابزاری که با OpenAI کار میکند صدا بزنید. فقط آدرس پایه و کلید را عوض کنید؛ هزینهٔ هر درخواست به اندازهٔ مصرف واقعی از کردیت کیف پول کم میشود.
آدرس پایه (base_url)
https://api.noqte.ai/v1اولین درخواست · POST /v1/chat/completions
# 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) نگه دارید و هرگز در کد سمت مرورگر یا اپ موبایل نگذارید.
- 01
کردیت بخرید
کلید API فقط برای حسابی ساخته میشود که کردیت خریده باشد. کردیت رایگان روزانه در API مصرف نمیشود.
- 02
کلید بسازید
در پنل، صفحهٔ «API کردیت»، یک کلید بسازید. کلید فقط یکبار نمایش داده میشود؛ آن را در متغیر محیطی نگه دارید.
- 03
آدرس پایه را عوض کنید
در کتابخانه یا ابزار خود base_url را آدرس زیر و api_key را کلید نقطه بگذارید. بقیهٔ کد همان کد OpenAI است.
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
}'# 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)نمونهٔ پاسخ
{
"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 کار میکند. کلیدی را که لو رفته از همان صفحه لغو کنید.
POST /v1/chat/completions HTTP/1.1
Host: api.noqte.ai
Authorization: Bearer sk-noqte-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json03 · Endpoints
مسیرهای API
همهٔ مسیرها زیر آدرس پایه هستند و با همان کلید کار میکنند. شناسهٔ مدلها را دستی ننویسید؛ از GET /v1/models بخوانید.
/v1/chat/completionsارسال گفتگو و گرفتن پاسخ؛ معمولی یا stream.
/v1/modelsفهرست مدلهایی که این کلید میتواند صدا بزند. مدلهایی که در endpoints آنها chat/completions آمده با این API کار میکنند.
/v1/usageموجودی کردیت کیف پول در فیلد balance_credits.
curl https://api.noqte.ai/v1/models \
-H "Authorization: Bearer $NOQTE_API_KEY"04 · Features
امکانات پشتیبانیشده
بدنهٔ درخواست و پاسخ همان قالب Chat Completions در OpenAI است.
stream
با stream: true پاسخ بهصورت رویدادهای data: میآید و با data: [DONE] تمام میشود. اگر stream_options.include_usage را true بگذارید، مصرف توکن در آخرین تکه برمیگردد.
فراخوانی ابزار
tools و tool_choice مثل OpenAI؛ پاسخ مدل tool_calls دارد و نتیجهٔ ابزار را با پیامی با role: "tool" و همان tool_call_id برمیگردانید. در stream هم کار میکند.
ورودی تصویر
در content پیام، بخشی با type: "image_url" بفرستید؛ لینک تصویر یا data URL (base64) هر دو پذیرفته میشوند.
سقف خروجی
max_tokens یا max_completion_tokens. اگر کردیت کیف پول برای سقف درخواستی کافی نباشد، پاسخ کوتاهتر میشود یا خطای 402 میگیرید.
نام مدل در پاسخ
فیلد model در پاسخ و در هر تکهٔ 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}
}'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)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 میخواند.
{
"error": {
"message": "The model is not enabled.",
"type": "invalid_request_error",
"param": null,
"code": "model_not_found"
}
}- 400
invalid_request_errorinvalid_messagesبدنه نامعتبر است؛ مثلاً
messagesآرایه نیست یا JSON درست نیست. - 401
authentication_error—کلید فرستاده نشده یا معتبر نیست.
- 402
insufficient_quotainsufficient_creditsکردیت کیف پول برای این درخواست کافی نیست.
- 403
permission_errormodel_not_allowed · scope_not_allowed · ip_not_allowedاین کلید به این مدل یا عملیات دسترسی ندارد، یا درخواست از IP مجاز کلید نیامده است.
- 403
permission_errorapi_credits_requiredحساب کردیت خریداریشده ندارد.
- 404
invalid_request_errormodel_not_foundشناسهٔ مدل فعال نیست؛ شناسه را از
GET /v1/modelsبخوانید. - 409
invalid_request_erroridempotency_conflictهمان
Idempotency-Keyبا بدنهٔ دیگری استفاده شده است. - 429
rate_limit_errorrate_limit_exceeded · concurrency_exceededتعداد درخواست در دقیقه یا درخواستهای همزمان زیاد است؛ بعد از
Retry-Afterدوباره بفرستید. - 429
rate_limit_errorcredit_limit_exceededکلید به سقف کردیتی که برایش گذاشتهاید رسیده است.
| HTTP | type | code | معنی |
|---|---|---|---|
| 400 | invalid_request_error | invalid_messages | بدنه نامعتبر است؛ مثلاً messages آرایه نیست یا JSON درست نیست. |
| 401 | authentication_error | — | کلید فرستاده نشده یا معتبر نیست. |
| 402 | insufficient_quota | insufficient_credits | کردیت کیف پول برای این درخواست کافی نیست. |
| 403 | permission_error | model_not_allowed · scope_not_allowed · ip_not_allowed | این کلید به این مدل یا عملیات دسترسی ندارد، یا درخواست از IP مجاز کلید نیامده است. |
| 403 | permission_error | api_credits_required | حساب کردیت خریداریشده ندارد. |
| 404 | invalid_request_error | model_not_found | شناسهٔ مدل فعال نیست؛ شناسه را از GET /v1/models بخوانید. |
| 409 | invalid_request_error | idempotency_conflict | همان Idempotency-Key با بدنهٔ دیگری استفاده شده است. |
| 429 | rate_limit_error | rate_limit_exceeded · concurrency_exceeded | تعداد درخواست در دقیقه یا درخواستهای همزمان زیاد است؛ بعد از Retry-After دوباره بفرستید. |
| 429 | rate_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 است.
کلید بسازید و اولین درخواست را بفرستید
کلید کردیت در چند ثانیه ساخته میشود، سقف کردیت آن قابل تنظیم است و هزینه از کیف پول همان حساب کم میشود.