GX10 Render-API (über das Relay)

Zwei Workflows auf der GX10, per HTTP für dich und deine Agents:

Basis-URL: https://ai.michalski-marketing.de · interaktive Doku: https://ai.michalski-marketing.de/docs

API-Key: auf der Startseite mit Google anmelden → Neuen Key anlegen. Der Key wird nur einmal angezeigt. Jede Anfrage braucht den Header Authorization: Bearer <key>. Keys nie in Repos oder in Prompts für fremde Dienste legen; einen verlorenen Key auf der Startseite widerrufen und einen neuen anlegen.

Ablauf

1. Referenzen hochladen → POST /v1/uploads (multipart, Feld file) → liefert eine id
   • Bilder (PNG/JPG/WebP) werden zu PNG, Audio (WAV/MP3/FLAC/M4A – bei einem Video mit Ton dessen Tonspur) zu WAV mono 24 kHz, max. 30 s.
2. Auftrag anlegen → POST /v1/images oder POST /v1/videos → liefert {"id": …, "status": "pending"}
   • Optionaler Header Idempotency-Key: <eigene-id>: Schickt dein Agent dieselbe Anfrage nach einem Netzfehler noch einmal, kommt der schon angelegte Auftrag zurück statt eines zweiten.

3. Status abfragen → GET /v1/jobs/{id} – alle 10–30 s reicht:

   Status	Bedeutung
   pending	wartet beim Relay; position = Platz in der Reihe
   queued	liegt auf der GX10 in der Warteschlange; position ≥ 1
   rendering	rechnet gerade (position 0)
   done	fertig → result_url
   failed	Fehler, Grund in error
   cancelled	abgebrochen

4. Ergebnis laden → GET /v1/jobs/{id}/result. Ergebnisse und Uploads werden nach 14 Tagen gelöscht (expires im Auftrag) – also zeitnah herunterladen.

Weitere: GET /v1/jobs (eigene Aufträge), DELETE /v1/jobs/{id} (solange er noch nicht rechnet), GET /v1/uploads, GET /v1/me (Limits und heutiger Verbrauch), GET /v1/health (ohne Key: ist die GX10 gerade erreichbar, runner_online, gx10_ready, paused).

Warteschlange: Die GX10 hat eine GPU und rendert auch eigene Produktionen. Deine Aufträge wechseln sich mit denen ab: höchstens einer wartet direkt hinter dem Render, der gerade läuft. Ist die GX10 aus oder pausiert, bleiben Aufträge auf pending und laufen später von selbst los. Zeiten: Bild ~1 min, Video ~1 min pro Sekunde Clip bei nativer Größe (15 s ≈ 15 min), mit megapixels: 0.5 etwa die Hälfte.

Tageslimits stehen in GET /v1/me (bei Bedarf beim Admin erhöhen lassen).

Bild: POST /v1/images

{"prompt": "Product photo of the bottle in Picture 1 on a wet black stone, soft rim light, studio, no text.",
 "refs": ["3f2a…"], "width": 1024, "height": 1024}

Video: POST /v1/videos

Variante A – strukturiert (empfohlen)

Du beschreibst Figuren/Orte/Objekte mit je einem Bild und die Einstellungen; die API schreibt daraus den H3-Brief.

{
  "subjects": [
    {"key": "ANNA", "kind": "character", "name": "Anna",
     "description": "a woman in her thirties with short red hair, wearing a green raincoat",
     "image": "a1b2…", "voice": "c3d4…", "voice_desc": "a calm, warm female voice"},
    {"key": "CAFE", "kind": "location", "name": "corner café",
     "description": "a small Berlin corner café at night, rain on the windows", "image": "e5f6…"},
    {"key": "CUP", "kind": "prop", "name": "travel mug",
     "description": "a matte black travel mug with a copper lid", "image": "g7h8…"}
  ],
  "shots": [
    "A medium shot in {CAFE}: {ANNA} sits at the window and lifts {CUP}, steam rising.",
    "A close-up of {ANNA!}, who smiles and says {ANNA~}: <d>[English] Some mornings need a little more warmth. </d>"
  ],
  "speakers": ["ANNA"],
  "summary": "Anna enjoys her coffee from the travel mug on a rainy evening.",
  "sound": "Soft rain on the window, quiet café murmur, a cup set down on wood.",
  "music": "A gentle, warm acoustic guitar motif under the scene.",
  "seconds": 10, "aspect": "9:16"
}

Variante B – eigener H3-Brief (für Fortgeschrittene)

brief = kompletter H3-ref2va-Brief (Abschnitte subject_definitions, summary, retention_analysis, detailed_description, overall_soundscape, non_diegetic_music) und tray = die Referenzen in Reihenfolge (upload, label klein-mit-bindestrichen, role: subject | environment | voice_timbre | music_style, note). <Subject n> / <Picture n> / <Audio n> im Brief zählen in der Reihenfolge des Trays. Die Antwort von GET /v1/jobs/{id} enthält bei Variante A den erzeugten Brief – gute Vorlage.

Erfahrungen (was H3 gut / schlecht kann)

• Schrift, Logos, Preise nie generieren lassen – H3 und Qwen erfinden Buchstaben. Logo, Claim, Endkarte und Untertitel nachträglich im Schnitt einsetzen. Im Stil-Absatz „no on-screen text, titles or logos“ lassen.
• Figuren: Model-Sheet (Front, ¾, Profil, Ganzkörper) als Referenz hält die Identität deutlich besser als ein Foto. Das Geschlecht immer in die description schreiben.
• Pro Einstellung den Ort nennen ({CAFE}), sonst rutscht H3 in den grauen Hintergrund der Sheets.
• Format zum Inhalt: 9:16 braucht Nahaufnahmen, breite Zweier-Einstellungen funktionieren dort schlecht.
• Dialog: kurze Sätze; H3 liest manchmal die summary als Erzähler vor, wenn die Dialogzeile sehr kurz ist – dann in sound schreiben: „No narrator and no voice-over: the only spoken words are the quoted dialogue lines.“
• Erst klein testen (megapixels: 0.5, 5 s), dann mit gleichem seed groß rendern.

Fehler

Manche Fehler meldet erst die GX10 (z. B. eine Datei, die sich dort nicht lesen lässt). Dann steht der Auftrag auf failed mit dem Grund in error.

Minimaler Python-Client

import time, uuid, requests
API, H = "https://ai.michalski-marketing.de", {"Authorization": "Bearer rr_…"}

def upload(path):
    with open(path, "rb") as f:
        r = requests.post(f"{API}/v1/uploads", headers=H, files={"file": f})
    r.raise_for_status()
    return r.json()["id"]

def run(kind, body, out):
    hdr = {**H, "Idempotency-Key": uuid.uuid4().hex}
    j = requests.post(f"{API}/v1/{kind}", headers=hdr, json=body).json()
    while j["status"] in ("pending", "queued", "rendering"):
        time.sleep(20)
        j = requests.get(f"{API}/v1/jobs/{j['id']}", headers=H).json()
    if j["status"] != "done":
        raise RuntimeError(j)
    with open(out, "wb") as f:
        f.write(requests.get(API + j["result_url"], headers=H).content)

ref = upload("produkt.png")
run("images", {"prompt": "The product in Picture 1 on a marble table, morning light.", "refs": [ref]}, "bild.png")