مستندات API چراغ

با یک کلید به همه‌ی مدل‌های چت، عکس و ویدیوی چراغ دسترسی داری. بخش چت کاملاً سازگار با OpenAI است: کتابخانه‌ی رسمی OpenAI را بردار، فقط base_url را عوض کن. هزینه‌ی هر درخواست به تومان از اعتبار حسابت کم می‌شود.

شروع سریع

1. وارد چراغ ← API شو و یک کلید بساز (شکلش cq_live_… است).
2. آدرس پایه: https://cheraq.ai/api/v1
3. اولین درخواست:

curl https://cheraq.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $CHERAQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "یک شعار کوتاه برای کافه بنویس"}]}'

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

کلید را در سرآیند Authorization: Bearer cq_live_… بفرست. اگر پراکسی یا هاستی این سرآیند را حذف می‌کند، همان کلید را در X-Api-Key هم می‌توانی بفرستی. کلید را فقط در سمت سرور نگه دار؛ هر کس کلید را داشته باشد از اعتبار تو خرج می‌کند. در صفحه‌ی API می‌بینی هر کلید چقدر خرج کرده و می‌توانی باطلش کنی.

فهرست مدل‌ها

GET /models همه‌ی مدل‌های قابل استفاده را با نوع، گزینه‌ها و هزینه‌ی تقریبی (به اعتبار؛ هر اعتبار = ۱ سنت دلار) برمی‌گرداند. به‌جای شناسه‌ی دقیق می‌توانی از این نام‌ها استفاده کنی:

• auto — مدل پیشنهادی چراغ برای همان نوع کار
• openai-latest — تازه‌ترین مدل پرچم‌دار OpenAI (برای چت و عکس)

curl https://cheraq.ai/api/v1/models -H "Authorization: Bearer $CHERAQ_KEY"
# → {"data":[{"id":"openai/gpt-6.1-sol","type":"chat","name":"…","recommended":true,"estimated_credits":{…}}, …], "usd_toman": 255357}

چت (سازگار با OpenAI)

POST /chat/completions — همان بدنه‌ی OpenAI: model، messages (نقش‌های system، user و assistant؛ محتوای چندبخشی با عکس هم پذیرفته می‌شود)، stream، max_tokens (تا ۳۲۰۰۰)، temperature و response_format با json_object.

Python با کتابخانه‌ی رسمی OpenAI:

from openai import OpenAI
client = OpenAI(api_key="cq_live_…", base_url="https://cheraq.ai/api/v1")
r = client.chat.completions.create(
    model="anthropic/claude-sonnet-5.5",
    messages=[{"role": "user", "content": "سه ایده‌ی پست اینستاگرام برای فروشگاه کفش"}],
)
print(r.choices[0].message.content)

JavaScript / Node با استریم:

import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.CHERAQ_KEY, baseURL: "https://cheraq.ai/api/v1" });
const stream = await client.chat.completions.create({ model: "auto", stream: true,
  messages: [{ role: "user", content: "یک ایمیل پیگیری مودبانه بنویس" }] });
for await (const part of stream) process.stdout.write(part.choices[0]?.delta?.content ?? "");

پاسخ همان شکل OpenAI است. در usage.credits هم می‌بینی چقدر اعتبار برای این درخواست کم شد.

ساخت عکس

POST /images یک کار در صف می‌سازد و فوراً با وضعیت ۲۰۲ جواب می‌دهد؛ نتیجه را از کارها بگیر.

• model (لازم)، prompt (لازم، تا ۴۰۰۰ حرف؛ فارسی هم می‌فهمد)
• n (۱ تا ۴)، aspect_ratio مثل 1:1، 9:16 یا 16:9، quality (auto | low | medium | high)، resolution
• reference_assets: تا ۸ شناسه‌ی عکس مرجع (برای ویرایش یا حفظ چهره و محصول)

curl https://cheraq.ai/api/v1/images -H "Authorization: Bearer $CHERAQ_KEY" -H "Content-Type: application/json" \
  -d '{"model": "openai-latest", "prompt": "عکس محصول یک فنجان قهوه روی میز چوبی، نور صبح", "aspect_ratio": "1:1"}'
# → 202 {"id":"…","status":"queued","credits_reserved":3.9, …}

ساخت ویدیو

POST /videos — مثل عکس، با duration (ثانیه)، resolution، aspect_ratio، generate_audio و reference_asset (برای جان دادن به یک عکس). ساخت ویدیو چند دقیقه طول می‌کشد.

curl https://cheraq.ai/api/v1/videos -H "Authorization: Bearer $CHERAQ_KEY" -H "Content-Type: application/json" \
  -d '{"model": "kwaivgi/kling-v3.0-std", "prompt": "دوربین آرام به فنجان قهوه نزدیک می‌شود، بخار بالا می‌رود", "duration": 5, "aspect_ratio": "9:16"}'

پیگیری کار و دریافت فایل

GET /jobs/{id} وضعیت را برمی‌گرداند: queued، running، done یا failed. هر چند ثانیه یک بار بپرس. وقتی کار done شد، در assets برای هر فایل یک url هست که با همان کلید دانلود می‌شود. کار ناموفق هزینه ندارد و اعتبار رزروشده برمی‌گردد.

import time, requests
H = {"Authorization": "Bearer cq_live_…"}
job = requests.post("https://cheraq.ai/api/v1/images", headers=H, json={"model": "auto", "prompt": "لوگوی مینیمال یک نانوایی"}).json()
while job["status"] in ("queued", "running"):
    time.sleep(3); job = requests.get(f"https://cheraq.ai/api/v1/jobs/{job['id']}", headers=H).json()
for a in job["assets"]:
    open(a["id"] + ".png", "wb").write(requests.get(a["url"], headers=H).content)

اعتبار حساب

curl https://cheraq.ai/api/v1/me -H "Authorization: Bearer $CHERAQ_KEY"
# → {"id":…, "credits":{"available":120.5,"paid":118,"free_today":2.5,"reserved":0}, "unit":"1 credit = 0.01 USD"}

خطاها و محدودیت‌ها

• 400 ورودی نامعتبر (متن خطا می‌گوید کدام فیلد) · 401 کلید نامعتبر یا باطل‌شده
• 402 اعتبار کافی نیست · 404 کار یا فایل پیدا نشد
• 429 درخواست زیاد یا بیش از ۸ کار هم‌زمان؛ کمی صبر کن و دوباره بفرست
• 5xx مشکل موقت؛ با فاصله‌ی چند ثانیه دوباره امتحان کن (چت ناموفق هزینه ندارد)

بدنه‌ی خطا همیشه {"error": "…"} است.

هزینه

هر مدل به نرخ روز دلار و به ازای مصرف واقعی حساب می‌شود: چت بر اساس توکن، عکس به ازای هر تصویر و ویدیو به ازای هر ثانیه. هزینه‌ی تقریبی هر مدل در /models هست. برای عکس و ویدیو، اول مبلغی رزرو می‌شود و بعد از ساخت فقط هزینه‌ی واقعی کم می‌شود.

MCP: چراغ به‌عنوان ابزار در Claude، Cursor و…

چراغ یک سرور MCP (Model Context Protocol) دارد: دستیارهای هوش مصنوعی مثل Claude، Cursor، VS Code یا n8n با همان کلید API به آن وصل می‌شوند و ابزارهای چراغ را خودشان صدا می‌زنند. هزینه‌ی هر ابزار مثل API از اعتبار حسابت کم می‌شود.

• آدرس: https://cheraq.ai/api/mcp (Streamable HTTP) با سرآیند Authorization: Bearer cq_live_…
• برای ابزارهایی که فقط آدرس می‌گیرند: https://cheraq.ai/api/mcp/cq_live_… (کلید داخل آدرس است؛ منتشرش نکن)
• ابزارها: instagram_reel_transcript (متن ریلز + کپشن و آمار)، instagram_profile، generate_image، generate_video، get_job، chat، list_models، get_balance

# Claude Code
claude mcp add --transport http cheraq https://cheraq.ai/api/mcp --header "Authorization: Bearer $CHERAQ_KEY"

# Cursor / VS Code (mcp.json)
{ "mcpServers": { "cheraq": { "url": "https://cheraq.ai/api/mcp", "headers": { "Authorization": "Bearer cq_live_…" } } } }

# Claude (web, Desktop, mobile) and ChatGPT: Add custom connector → URL only, the key inside
https://cheraq.ai/api/mcp/cq_live_…

ساخت عکس تا حدود ۷۵ ثانیه منتظر نتیجه می‌ماند و لینک می‌دهد (لینک‌ها ۷ روز معتبرند)؛ ویدیو چند دقیقه طول می‌کشد، پس شناسه‌ی کار برمی‌گردد و با get_job لینکش را می‌گیری.

افزونه‌ی وردپرس

اگر سایت وردپرسی داری، لازم نیست چیزی بنویسی: پلاگین وردپرس چراغ با یک کلیک وصل می‌شود و مقاله، به‌روزرسانی مطالب، توضیح محصول، سئو و چت پشتیبانی را با تأیید تو انجام می‌دهد. این افزونه همچنین چراغ را به‌عنوان یک «ارائه‌دهنده‌ی هوش مصنوعی» در بخش Connectors خود وردپرس ثبت می‌کند تا افزونه‌های دیگر هم بتوانند از آن استفاده کنند.

سؤالی داری؟ از تماس با ما موضوع «API و توسعه‌دهنده‌ها» را انتخاب کن.