Tham khảo API

Mọi endpoint, cùng hình dạng yêu cầu và phản hồi của nó. Tất cả các tuyến đều tương đối với https://sketchie.ai/api.

Quy ước

Mọi endpoint /v1/* đều cần tiêu đề Authorization: Bearer sk_.... Lỗi trả về dưới dạng JSON với cờ error và một message:

Phản hồi lỗi

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

Các endpoint tạo bị giới hạn tốc độ 20 yêu cầu mỗi phút. Tất cả các endpoint khác chia sẻ giới hạn 200 mỗi phút.

Tạo một giải thích

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

Bắt đầu một lần tạo và trả về 202 Accepted với bản ghi trong hàng đợi. Thăm dò lấy một giải thích cho đến khi nó ở trạng thái ready.

Thân yêu cầu

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

Trường	Kiểu	Ghi chú
`input`	string	Nội dung cần giải thích. Một prompt ngắn hoặc toàn văn tài liệu. Bắt buộc trừ khi có `source` hoặc `sceneGraph`. Bí danh: `prompt`.
`length`	string or number	Độ dài mục tiêu dưới dạng `"M:SS"` (`"0:30"`, `"1:00"`) hoặc giây. Bội số dương của 30, tối đa 360. Bỏ qua để có độ dài tự động. Bí danh: `lengthSeconds` (số).
`voice`	string	Tùy chọn. Một tham chiếu giọng. Mặc định là người dẫn tiêu chuẩn (Nora). Xem Giọng đọc.
`language`	string	Tùy chọn. Một mã ngôn ngữ được hỗ trợ (mặc định `en`). Xem Ngôn ngữ.
`aspect`	string	Tùy chọn. `16:9` (mặc định), `9:16` hoặc `1:1`.
`source`	string	Tùy chọn. Một tài liệu, bài viết hoặc bản chép để biến thành một giải thích. Khi có, `input` trở thành hướng dẫn tùy chọn.
`preset`	string	Kiểu vẽ tùy chọn: `marker` (mặc định), `chalkboard`, `pencil`, `blueprint`, `crayon`, `clean`.
`fillMode`	string	Kỹ thuật đổ màu tiết lộ tùy chọn: `A`, `B`, `C` (mặc định) hoặc `D`.
`sceneGraph`	object	Tùy chọn. Một scene graph được soạn sẵn. Worker bỏ qua việc tạo đồ thị và render trực tiếp, nhưng endpoint này vẫn tạo một giải thích mới và tiêu tốn hạn mức miễn phí thông thường hoặc hạn ngạch gói trả phí của người gọi. Để chỉnh sửa một giải thích hiện có, dùng chỉnh sửa một giải thích.

Trả về bản ghi giải thích: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null cho đến khi sẵn sàng) và sceneGraph (null cho đến khi được tạo). 400 trả về cho một input rỗng không có source, một length sai định dạng, hoặc một aspect, preset, fillMode hoặc language không hợp lệ.

Lấy một giải thích

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

Trả về bản ghi đầy đủ: status hiện tại, videoUrl khi đã ready, sceneGraph có thể chỉnh sửa, lịch sử phiên bản (versions) và các chunks cảnh của phiên bản đầu. Một id thiếu trả về 404.

Liệt kê các giải thích

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

Liệt kê các giải thích của khóa gọi, mới nhất trước. Giới hạn ở chủ sở hữu khóa. limit được kẹp từ 1 đến 100 (mặc định 50). Trả về tóm tắt nhẹ (không scene graph hay phiên bản). Dùng lấy một giải thích cho bản ghi đầy đủ.

Chỉnh sửa một giải thích

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

Cái nêm của khả năng chỉnh sửa. Biến một chỉ dẫn ngôn ngữ đơn giản thành một lần render lại có mục tiêu. Chỉ những cảnh bị ảnh hưởng mới render lại, tạo ra một phiên bản mới. Trả về 202 với phiên bản trong hàng đợi. Thăm dò lấy một giải thích cho đến khi phiên bản đầu ở trạng thái ready. Điều này bổ sung vào video hiện có, nên không tiêu tốn thêm một suất tạo video miễn phí. Lần render lại đầu tiên của mỗi video là miễn phí. Các lần sau dùng phút gói trả phí, và các tài khoản miễn phí được yêu cầu bắt đầu một gói. Giải thích phải đã ở trạng thái ready (nếu không 409).

Thân yêu cầu

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

Hoàn nguyên về một phiên bản

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

Trỏ lại đầu về một phiên bản sẵn sàng trước đó và phản chiếu đồ thị và video của nó lên bản ghi. Mục tiêu phải là một phiên bản ready có video (nếu không 409).

Thân yêu cầu

{ "versionId": "..." }

Luồng trạng thái trực tiếp

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

Một luồng Server-Sent Events (text/event-stream). Mở một kết nối và mọi chuyển đổi trạng thái trên bất kỳ giải thích nào của bạn đều đến dưới dạng một khung event: status, nên bạn có thể cập nhật trạng thái "video sẵn sàng" ngay khi worker hoàn tất thay vì thăm dò. Luồng được giới hạn ở chủ sở hữu khóa của bạn.

Giọng đọc

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

Danh mục giọng thuyết minh. ?language=<code> tùy chọn lọc theo các giọng bản địa của ngôn ngữ đó. Trả về voices (mỗi giọng có một name thân thiện, id để truyền làm voice, language, isDefault và một preview_url có thể phát) cùng default toàn cục. Xem Giọng đọc.

Ngôn ngữ

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

Các ngôn ngữ thuyết minh được hỗ trợ, dưới dạng { code, label, native }. Mọi code là một language hợp lệ khi tạo. Xem Ngôn ngữ.

Trạng thái tài khoản

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

Trả về videosGenerated (trọn đời), image tài khoản và isAdmin. Yêu cầu xác thực.

Trạng thái thanh toán

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

Yêu cầu xác thực và trả về 200 cho cả tài khoản miễn phí và trả phí. Một tài khoản miễn phí trả về plan: "free" với videoAllowance, videosUsed và videosRemaining. Một tài khoản trả phí cũng trả về planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining và bonusMinutes.

Cấu hình thời gian chạy và tình trạng

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

Công khai. Trả về { "authEnforced": true }. Một kiểm tra sống nằm ở GET /health.