Mit KI entwickeln: REST-API, CLI und SDKs von OpenMates

Du musst kein eigenes Modell trainieren, um etwas Nützliches mit KI zu bauen. Ein Spiel kann fragen, ob ein Spielzug sinnvoll ist. Eine Website kann ein Ergebnis erklären. Ein Python-Skript kann aus einer Idee einen ersten Entwurf machen.

OpenMates bietet eine REST-API, eine Kommandozeile (CLI) sowie SDKs für TypeScript und Python. Wähle die Schnittstelle, die zu deinem Projekt passt. Solange das gemeinsame kostenlose Kontingent verfügbar ist, kannst du geeignete Gastanfragen ohne Konto, API-Schlüssel oder Zahlungsmittel ausprobieren.

Text oder Entscheidung?

Ein Chat eignet sich für erzeugten Text: eine Erklärung, eine Geschichte oder Feedback in ganzen Sätzen. Mit ai.decide fragst du eine strukturierte Einschätzung ab. Du übergibst state mit den bekannten Fakten und questions mit deinen Fragen. Jede Frage enthält einen type, instructions und bei Bedarf criteria.

• noul: eine Ja-Nein-Einschätzung als Wahrscheinlichkeit zwischen 0 und 1 im Antwortfeld noul. Ein Wert nahe 0,5 drückt Unsicherheit aus.
• choice: eine Auswahl zwischen Kategorien, die du im Objekt criteria festlegst. Die Antwort enthält choice und die Wahrscheinlichkeiten der Kategorien unter probabilities.
• score: eine Bewertung anhand einer geordneten Liste von Bewertungsstufen in criteria. Die Antwort enthält score, eine legend und Wahrscheinlichkeiten für die Stufen. Die Skala beginnt bei 0 und endet bei der Anzahl der Stufen minus 1.

Die Regeln bleiben bei deinem Spiel. Prüfe das Ergebnis, behandle Unsicherheit und halte eine einfache Ersatzaktion bereit. Die Wahrscheinlichkeit ist eine Einschätzung anhand deiner Angaben und keine Garantie dafür, was tatsächlich passiert.

TypeScript: KI in deiner App

Installiere das Paket in deinem Projekt:

npm install openmates

import { OpenMates, OpenMatesSignupRequiredError } from "openmates";

const om = new OpenMates();
try {
  const reply = await om.chats.send("Schlage einen Namen für ein Weltraumspiel vor.");
  console.log(reply.content);
} catch (error) {
  if (error instanceof OpenMatesSignupRequiredError) {
    console.log(error.message);
  } else {
    throw error;
  }
}

new OpenMates() verwendet ohne Schlüssel automatisch den Gastzugang und nutzt dein Konto, wenn OPENMATES_API_KEY konfiguriert ist. Du brauchst keinen API-Schlüssel eines KI-Anbieters.

Jetzt fragst du eine strukturierte Entscheidung ab:

const result = await om.apps.ai.decide({
  state: { energy: 2, maximumEnergy: 10, enemiesNearby: false },
  questions: {
    rest: {
      type: "noul",
      instructions: "Sollte die Figur sich vor dem Erkunden ausruhen?",
      criteria: {
        true: "Die Energie ist niedrig und Ausruhen ist sicher.",
        false: "Die Energie reicht aus oder Ausruhen ist gefährlich."
      }
    }
  }
});
console.log(result);

Die Skill-Antwort enthält die Entscheidung unter data, die benannten Antworten unter data.answers. Schau dir die Antwort an, bevor du damit das Spiel steuerst. Fehlende Informationen können die Einschätzung verändern.

Python: dieselbe Idee als Skript

pip install openmates

from openmates import OpenMates, OpenMatesSignupRequiredError

om = OpenMates()
try:
    reply = om.chats.send("Schlage einen Namen für ein Weltraumspiel vor.")
    print(reply.content)
    result = om.apps.ai.decide({
        "state": {"energy": 2, "enemiesNearby": False},
        "questions": {
            "rest": {
                "type": "noul",
                "instructions": "Sollte die Figur sich vor dem Erkunden ausruhen?"
            }
        }
    })
    print(result["data"]["answers"]["rest"])
except OpenMatesSignupRequiredError as error:
    print(str(error))

OpenMates() nutzt dein Konto, wenn OPENMATES_API_KEY konfiguriert ist, und sonst bei geeigneten Anfragen den Gastzugang.

CLI: direkt im Terminal ausprobieren

Das npm-Paket enthält auch die CLI. Installiere es global, damit du openmates direkt aufrufen kannst:

npm install -g openmates
openmates chats new "Schlage einen Namen für ein Weltraumspiel vor."

Eine Entscheidung kannst du als JSON übergeben:

openmates apps ai decide --input '{"state":{"energy":2,"enemiesNearby":false},"questions":{"rest":{"type":"noul","instructions":"Sollte die Figur sich vor dem Erkunden ausruhen?"}}}'

Bei einer frischen Installation können geeignete Anfragen den Gastzugang verwenden. Eine bestehende Anmeldung oder ein konfigurierter API-Schlüssel kann stattdessen den Kontozugang nutzen.

REST: aus jeder Programmiersprache aufrufen

Ein SDK verpackt HTTP-Anfragen in bequeme Methoden. Du kannst REST auch direkt ansprechen, ohne API-Schlüssel oder eigenen Identitätsheader:

curl https://api.openmates.org/v1/anonymous/apps/ai/skills/decide -H 'Content-Type: application/json' -d '{"state":{"energy":2,"enemiesNearby":false},"questions":{"rest":{"type":"noul","instructions":"Sollte die Figur sich vor dem Erkunden ausruhen?"}}}'

Du musst keine Kennung einrichten. Wenn du später einen Kontozugang einbaust, gehören dessen API-Schlüssel auf einen vertrauenswürdigen Server.

Ein Bild kann Teil einer Entscheidung sein

Mit Jev 1.14 kannst du auch Bildentscheidungen ausprobieren. Zeichne zum Beispiel ein einfaches Spielfeld, speichere es als board.png und frage, ob ein freier Weg zum Ausgang existiert. Das Modell bewertet das Bild; es erzeugt oder bearbeitet kein Bild.

In Node.js liest du die Datei und kodierst ihre Bytes:

import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";
import { OpenMates } from "openmates";

const om = new OpenMates();
const ref = randomUUID();
const image = (await readFile("board.png")).toString("base64");
const result = await om.apps.ai.decide({
  state: { board: ref },
  questions: {
    clear_path: {
      type: "noul",
      instructions: "Gibt es auf dem Spielfeld einen freien Weg zum Ausgang?"
    }
  },
  assets: { [ref]: { type: "image", format: "png", data_base64: image } }
});
console.log(result);

In Python sieht dieselbe Anfrage so aus:

import base64
import uuid
from pathlib import Path
from openmates import OpenMates

om = OpenMates()
ref = str(uuid.uuid4())
image = base64.b64encode(Path("board.png").read_bytes()).decode("ascii")
result = om.apps.ai.decide({
    "state": {"board": ref},
    "questions": {
        "clear_path": {
            "type": "noul",
            "instructions": "Gibt es auf dem Spielfeld einen freien Weg zum Ausgang?"
        }
    },
    "assets": {ref: {"type": "image", "format": "png", "data_base64": image}}
})
print(result["data"]["answers"])

Das Objekt assets enthält die eigentlichen Bilddaten. Sein UUID-Schlüssel ist ein Verweis: Setze ihn als Zeichenfolgenwert in state, Anweisungen oder Kriterien an die Stelle, an die das Bild gehört. Jedes Bild muss referenziert werden. Verwende für eine JPEG-Datei jpg oder jpeg statt png. Du brauchst keinen Anbieterschlüssel oder besonderen Header; OpenMates übernimmt den Anbieteraufruf.

Die Funktion ist experimentell und für Prototypen gedacht. Bereite lokal ein unbewegtes PNG oder JPEG vor, dessen beide Seiten zwischen 280 und 1568 Pixeln liegen und dessen Datei höchstens 1 MiB groß ist. Eine Anfrage unterstützt höchstens vier Bilder und insgesamt 4 MiB dekodierte Bilddaten. Zustand und Fragen müssen unabhängig davon in 16 KiB passen, die gesamte JSON-Anfrage in 6 MiB. Ein kleines Spielfeldbild ist ein guter Anfang.

Bildanfragen gehen direkt an TypeSafe, ohne OpenRouter als Ausweichanbieter. Ihre Bildtokens verbrauchen dasselbe kostenlose Kontingent oder Kontoguthaben. Behandle Kontingent- und Anbieterfehler wie in den vorherigen Beispielen. Dieser direkte Weg lädt keine Bild-URLs und speichert keinen Upload; der separate Kontoupload benötigt weiterhin eine Registrierung. Sende nur Bilder, die du mit dem Anbieter teilen möchtest. Die vorübergehende Verarbeitung durch OpenMates garantiert keine speicherfreie Verarbeitung bei TypeSafe.

So funktioniert das kostenlose Kontingent

Kostenlose Tests nutzen ein gemeinsames Kontingent des Dienstes mit Tages-, Wochen- und Monatsgrenzen. Dazu kommt eine Grenze für deine öffentliche IP-Adresse. Es gibt keine zugesicherte feste Anzahl kostenloser Anfragen: Anfragen kosten unterschiedlich viel, und andere Menschen nutzen denselben Vorrat. Im Schul-WLAN können mehrere Personen dasselbe IP-Limit teilen.

Das Tagesfenster beginnt um Mitternacht UTC neu. Dadurch verschwinden Wochen- oder Monatsgrenzen nicht. Auch die Verfügbarkeit der KI-Anbieter kann Anfragen beeinflussen.

Den Status fragst du in TypeScript mit await om.anonymous.status(), in Python mit om.anonymous.status() oder über REST ab:

curl https://api.openmates.org/v1/anonymous/free-usage/status

Der Status ist eine Orientierung und keine Reservierung. Ein positiver verbleibender Prozentsatz bedeutet nicht, dass jede Anfrage hineinpasst. Eine Anfrage kann mehr Spielraum benötigen, als sie am Ende tatsächlich kostet. Halte Anfragen kurz und behandle Ablehnungen.

Passt eine Gastanfrage nicht in das verfügbare Kontingent, antwortet die API mit HTTP 429, detail.signup_required: true und einer verständlichen Nachricht, dass du zum Weitermachen ein Konto brauchst. Beide SDKs stellen dafür OpenMatesSignupRequiredError bereit, wie in den Beispielen oben. Zeige die Nachricht an, statt endlos erneut anzufragen. Eine Störung beim KI-Anbieter ist ein eigener Fall und kann HTTP 503 auslösen. Eine Registrierung behebt sie nicht.

Zum Ausprobieren geeigneter kostenloser Funktionen brauchst du kein Zahlungsmittel. Der Gastzugang unterstützt Textchats und geeignete Skills, die Ergebnisse direkt zurückgeben und keine Kontodaten verändern. Uploads, gespeicherte Kontoinhalte und andere Kontoaktionen benötigen eine Registrierung. Danach gelten die normalen Kontoguthaben und Limits. Ein Konto verspricht keine unbegrenzte kostenlose Nutzung.

Baue eine kleine Sache

Beginne mit einer Spielfigur, die um Rat fragt, einer Seite, die ein Ergebnis erklärt, oder einem Skript, das Möglichkeiten bewertet. Verwende harmlose Eingaben und schicke bei Experimenten keine privaten Informationen mit. Gib die Antwort aus, verstehe ihre Struktur und verbinde sie dann mit deiner eigenen Logik.

Schau in die Entwicklerdokumentation oder den offenen Quellcode. Du kannst mit wenigen Zeilen anfangen und dein Projekt Schritt für Schritt wachsen lassen.