API-Referenz

Jeder Endpunkt, mit seiner Anfrage- und Antwortform. Alle Routen sind relativ zu https://sketchie.ai/api.

Konventionen

Jeder /v1/*-Endpunkt erfordert den Authorization: Bearer sk_...-Header. Fehler kommen als JSON mit einem error-Flag und einer message zurück:

Fehlerantwort

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

Generierungs-Endpunkte sind auf 20 Anfragen pro Minute begrenzt. Alle anderen teilen sich ein Limit von 200 pro Minute.

Ein Erklärvideo erstellen

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

Startet eine Generierung und gibt 202 Accepted mit dem eingereihten Datensatz zurück. Frage ein Erklärvideo abrufen ab, bis es ready ist.

Anfrage-Body

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

Feld	Typ	Hinweise
`input`	string	Was erklärt werden soll. Ein kurzer Prompt oder der volle Dokumenttext. Erforderlich, außer `source` oder `sceneGraph` ist vorhanden. Alias: `prompt`.
`length`	string or number	Ziel-Länge als `"M:SS"` (`"0:30"`, `"1:00"`) oder Sekunden. Ein positives Vielfaches von 30, bis zu 360. Lass weg für automatische Länge. Alias: `lengthSeconds` (Zahl).
`voice`	string	Optional. Eine Stimm-Ref. Standard ist die Standard-Erzählstimme (Nora). Siehe Stimmen.
`language`	string	Optional. Ein unterstützter Sprachcode (Standard `en`). Siehe Sprachen.
`aspect`	string	Optional. `16:9` (Standard), `9:16` oder `1:1`.
`source`	string	Optional. Ein Dokument, Artikel oder Transkript, das in ein Erklärvideo verwandelt wird. Wenn vorhanden, wird `input` zu optionaler Anleitung.
`preset`	string	Optionaler Zeichenstil: `marker` (Standard), `chalkboard`, `pencil`, `blueprint`, `crayon`, `clean`.
`fillMode`	string	Optionale Reveal-Fülltechnik: `A`, `B`, `C` (Standard) oder `D`.
`sceneGraph`	object	Optional. Ein vorab erstellter Scene Graph. Der Worker überspringt die Graph-Generierung und rendert ihn direkt, aber dieser Endpunkt erstellt trotzdem ein neues Erklärvideo und verbraucht das normale Gratis-Kontingent oder die Quote des bezahlten Plans. Um ein bestehendes Erklärvideo zu bearbeiten, nutze ein Erklärvideo bearbeiten.

Gibt den Erklärvideo-Datensatz zurück: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null bis fertig) und sceneGraph (null bis generiert). Ein 400 kommt bei leerem Input ohne Source, einer fehlerhaften Länge oder einem ungültigen aspect, preset, fillMode oder language zurück.

Ein Erklärvideo abrufen

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

Gibt den vollständigen Datensatz zurück: aktueller status, die videoUrl sobald ready, der editierbare sceneGraph, die Versionshistorie (versions) und die Szenen-chunks der Hauptversion. Eine fehlende id gibt 404 zurück.

Erklärvideos listen

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

Listet die Erklärvideos des aufrufenden Schlüssels, neueste zuerst. Auf den Schlüsselinhaber beschränkt. limit wird auf 1 bis 100 begrenzt (Standard 50). Gibt leichte Zusammenfassungen zurück (kein Scene Graph, keine Versionen). Nutze ein Erklärvideo abrufen für den vollen Datensatz.

Ein Erklärvideo bearbeiten

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

Der Editierbarkeits-Keil. Verwandle eine Anweisung in einfacher Sprache in ein gezieltes Neu-Rendern. Nur die betroffenen Szenen werden neu gerendert und erzeugen eine neue Version. Gibt 202 mit der eingereihten Version zurück. Frage ein Erklärvideo abrufen ab, bis die Hauptversion ready ist. Dies hängt an das bestehende Video an, verbraucht also keinen weiteren Gratis-Video-Erstellungsplatz. Das erste Neu-Rendern jedes Videos ist gratis. Spätere nutzen Minuten des bezahlten Plans, und Gratis-Konten werden gebeten, einen Plan zu starten. Das Erklärvideo muss bereits ready sein (sonst 409).

Anfrage-Body

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

Auf eine Version zurücksetzen

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

Setzt die Hauptversion auf eine frühere fertige Version und spiegelt deren Graph und Video auf den Datensatz. Das Ziel muss eine ready-Version mit Video sein (sonst 409).

Anfrage-Body

{ "versionId": "..." }

Live-Status-Stream

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

Ein Server-Sent-Events-Stream (text/event-stream). Öffne eine Verbindung und jeder Statuswechsel bei einem deiner Erklärvideos kommt als event: status-Frame an, sodass du einen "Video fertig"-Zustand in dem Moment aktualisieren kannst, in dem der Worker fertig ist, statt abzufragen. Der Stream ist auf deinen Schlüsselinhaber beschränkt.

Stimmen

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

Der Erzählstimmen-Katalog. Das optionale ?language=<code> filtert auf Stimmen, die in dieser Sprache nativ sind. Gibt voices zurück (jede mit einem freundlichen name, der id zum Übergeben als voice, language, isDefault und einer abspielbaren preview_url) plus das globale default. Siehe Stimmen.

Sprachen

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

Die unterstützten Erzählsprachen, als { code, label, native }. Jeder code ist beim Erstellen ein gültiger language-Wert. Siehe Sprachen.

Kontostatus

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

Gibt videosGenerated (lebenslang), das Konto-image und isAdmin zurück. Erfordert Authentifizierung.

Abrechnungsstatus

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

Erfordert Authentifizierung und gibt 200 für Gratis- und bezahlte Konten zurück. Ein Gratis-Konto gibt plan: "free" mit videoAllowance, videosUsed und videosRemaining zurück. Ein bezahltes Konto gibt außerdem planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining und bonusMinutes zurück.

Laufzeit-Config und Health

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

Öffentlich. Gibt { "authEnforced": true } zurück. Ein Liveness-Check liegt bei GET /health.