مرجع API

هر نقطه پایانی، با شکل درخواست و پاسخ آن. همه مسیرها نسبت به https://sketchie.ai/api هستند.

قراردادها

هر نقطه پایانی /v1/* به سرآیند Authorization: Bearer sk_... نیاز دارد. خطاها به‌صورت JSON با پرچم error و یک message برمی‌گردند:

پاسخ خطا

{
  "error": true,
  "message": "length must be a positive multiple of 30 seconds, at most 360"
}

نقاط پایانی تولید به ۲۰ درخواست در دقیقه محدود شده‌اند. همه نقاط پایانی دیگر یک محدودیت ۲۰۰ در دقیقه را به اشتراک می‌گذارند.

ساخت یک توضیح

POST https://sketchie.ai/api/v1/explainer

یک تولید را آغاز می‌کند و 202 Accepted را با رکورد در صف برمی‌گرداند. دریافت یک توضیح را نظرسنجی کنید تا ready شود.

بدنه درخواست

{
  "input": "Explain how DNS resolves a domain name",
  "length": "0:30",
  "aspect": "16:9",
  "voice": "sketchie:sulafat",
  "language": "en"
}

فیلد	نوع	یادداشت‌ها
`input`	string	چه چیزی توضیح داده شود. یک پرامپت کوتاه یا متن کامل سند. الزامی مگر اینکه `source` یا `sceneGraph` حاضر باشد. نام مستعار: `prompt`.
`length`	string or number	طول هدف به‌صورت `"M:SS"` (`"0:30"`، `"1:00"`) یا ثانیه. مضرب مثبت ۳۰، تا ۳۶۰. برای طول خودکار حذف کنید. نام مستعار: `lengthSeconds` (عدد).
`voice`	string	اختیاری. یک مرجع صدا. پیش‌فرض راوی استاندارد (Nora). به صداها نگاه کنید.
`language`	string	اختیاری. یک کد زبان پشتیبانی‌شده (پیش‌فرض `en`). به زبان‌ها نگاه کنید.
`aspect`	string	اختیاری. `16:9` (پیش‌فرض)، `9:16`، یا `1:1`.
`source`	string	اختیاری. یک سند، مقاله یا رونوشت برای تبدیل به توضیح. وقتی حاضر باشد، `input` به راهنمای اختیاری تبدیل می‌شود.
`preset`	string	سبک ترسیم اختیاری: `marker` (پیش‌فرض)، `chalkboard`، `pencil`، `blueprint`، `crayon`، `clean`.
`fillMode`	string	تکنیک پرکردن آشکارسازی اختیاری: `A`، `B`، `C` (پیش‌فرض)، یا `D`.
`sceneGraph`	object	اختیاری. یک scene graph از پیش نوشته‌شده. کارگر تولید گراف را رد می‌کند و آن را مستقیماً render می‌کند، اما این نقطه پایانی هنوز یک توضیح جدید می‌سازد و سهمیه رایگان معمول یا سهمیه پلن پولی فراخوان‌کننده را مصرف می‌کند. برای ویرایش یک توضیح موجود، از ویرایش یک توضیح استفاده کنید.

رکورد توضیح را برمی‌گرداند: id، status، prompt، lengthSeconds، voice، language، aspect، videoUrl (تا آماده‌شدن null) و sceneGraph (تا تولید null). برای input خالی بدون source، length بدشکل، یا aspect، preset، fillMode یا language نامعتبر، 400 برمی‌گردد.

دریافت یک توضیح

GET https://sketchie.ai/api/v1/explainer/:id

رکورد کامل را برمی‌گرداند: status فعلی، videoUrl پس از ready، sceneGraph قابل ویرایش، تاریخچه نسخه‌ها (versions) و chunks صحنه نسخه اصلی. یک id ناموجود 404 برمی‌گرداند.

فهرست کردن توضیح‌ها

GET https://sketchie.ai/api/v1/explainer?limit=50

توضیح‌های کلید فراخوان را فهرست می‌کند، ابتدا جدیدترین. محدود به مالک کلید. limit از ۱ تا ۱۰۰ محدود می‌شود (پیش‌فرض ۵۰). خلاصه‌های سبک برمی‌گرداند (بدون scene graph یا نسخه‌ها). برای رکورد کامل از دریافت یک توضیح استفاده کنید.

ویرایش یک توضیح

POST https://sketchie.ai/api/v1/explainer/:id/edit

گوه ویرایش‌پذیری. یک دستور به زبان ساده را به یک render مجدد هدفمند تبدیل کنید. فقط صحنه‌های متأثر دوباره render می‌شوند و نسخه‌ای جدید می‌سازند. 202 را با نسخه در صف برمی‌گرداند. دریافت یک توضیح را نظرسنجی کنید تا نسخه اصلی ready شود. این به ویدیوی موجود اضافه می‌شود، پس یک جایگاه ساخت ویدیوی رایگان دیگر مصرف نمی‌کند. اولین render مجدد هر ویدیو رایگان است. render‌های بعدی از دقایق پلن پولی استفاده می‌کنند و از حساب‌های رایگان خواسته می‌شود یک پلن آغاز کنند. توضیح باید از قبل ready باشد (وگرنه 409).

بدنه درخواست

{ "instruction": "Make the title scene shorter and warmer" }

بازگردانی به یک نسخه

POST https://sketchie.ai/api/v1/explainer/:id/revert

سر را به یک نسخه آماده قبلی بازنشانه می‌کند و گراف و ویدیوی آن را روی رکورد بازتاب می‌دهد. هدف باید یک نسخه ready با ویدیو باشد (وگرنه 409).

بدنه درخواست

{ "versionId": "..." }

جریان وضعیت زنده

GET https://sketchie.ai/api/v1/explainer/events

یک جریان Server-Sent Events (text/event-stream). یک اتصال باز کنید و هر انتقال وضعیت روی هر یک از توضیح‌هایتان به‌صورت یک قاب event: status می‌رسد، بنابراین می‌توانید در لحظه‌ای که کارگر تمام می‌کند وضعیت «ویدیو آماده» را به‌جای نظرسنجی به‌روزرسانی کنید. جریان محدود به مالک کلید شماست.

صداها

GET https://sketchie.ai/api/v1/voices

کاتالوگ صداهای روایت. ?language=<code> اختیاری به صداهای بومی آن زبان فیلتر می‌کند. voices را برمی‌گرداند (هر کدام با یک name ساده، id برای ارسال به‌عنوان voice، language، isDefault و یک preview_url قابل پخش) به‌علاوه default سراسری. به صداها نگاه کنید.

زبان‌ها

GET https://sketchie.ai/api/v1/languages

زبان‌های روایت پشتیبانی‌شده، به‌صورت { code, label, native }. هر code یک language معتبر هنگام ساخت است. به زبان‌ها نگاه کنید.

وضعیت حساب

GET https://sketchie.ai/api/v1/account/state

videosGenerated (مادام‌العمر)، image حساب و isAdmin را برمی‌گرداند. به احراز هویت نیاز دارد.

وضعیت صورتحساب

GET https://sketchie.ai/api/v1/billing/status

به احراز هویت نیاز دارد و برای هر دو حساب رایگان و پولی 200 برمی‌گرداند. یک حساب رایگان plan: "free" را با videoAllowance، videosUsed و videosRemaining برمی‌گرداند. یک حساب پولی همچنین planLabel، billingInterval، trialStatus، quotaMinutes، minutesUsedThisPeriod، minutesRemaining و bonusMinutes را برمی‌گرداند.

پیکربندی زمان اجرا و سلامت

GET https://sketchie.ai/api/config

عمومی. { "authEnforced": true } را برمی‌گرداند. یک بررسی سرزندگی در GET /health قرار دارد.