Storyboard per Films-API rendern: ein Aufruf, alle Szenen

Ein einzelner Prompt ergibt einen Clip. Ein Film ist eine Folge von Clips, die einen Look teilen und zusammengeschnitten werden, und der Filmmodus des Studios baut einen interaktiv – Szene hinzufügen, rendern, die nächste hinzufügen. Die Films-API macht dasselbe ohne Klicken: das Storyboard einmal definieren, jede Szene mit einem Aufruf drehen, die Jobs pollen, veröffentlichen. Wenn du zehn Varianten desselben Spots für zehn Kunden produzierst, ist das der Endpoint, den du gesucht hast.

Ein Film ist ein Rezept, nie ein Medium

POST /v1/films speichert einen Titel und ein data-Objekt, unverändert. Die API interpretiert das Rezept erst, wenn du es renderst, und Renders landen immer in deiner Bibliothek unter „Kreationen“, nie im Film. Zwei Teile:

• look – was alle Szenen gemeinsam haben: model, aspect, filmType, era, tempo, cameraType, lens, aperture, resolution.
• scenes – ein geordnetes Array aus { prompt, shot, seconds, cast }. shot ist eine Kamerabewegung, cast eine Liste deiner Charakter-IDs.

curl https://eroq.ai/v1/films \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rooftop night — cut 1",
    "data": {
      "look": {
        "model": "eroq-motion-one", "aspect": "16:9",
        "filmType": "noir", "era": "1960s", "tempo": "tense",
        "cameraType": "35mm", "lens": "anamorphic", "aperture": "f1-4"
      },
      "scenes": [
        { "prompt": "A woman in a silver dress steps out onto a rooftop bar at dusk, city lights flickering on below, slow pan following her to the railing, warm practicals against the deep blue sky, wind in her hair, expectant mood.", "shot": "slow-pan", "seconds": 5 },
        { "prompt": "Close-up of her hands on the cold railing, a glass of something amber beside them, push-in as the skyline blurs behind, neon reflections crawling across the glass, quiet and tense.", "shot": "push-in", "seconds": 5 },
        { "prompt": "Wide shot from behind as she turns toward the door, a silhouette waiting there against the bar light, crane-up revealing the whole rooftop and the city beyond, patient, ominous mood.", "shot": "crane-up", "seconds": 10 }
      ]
    }
  }'

Die Antwort enthält die id des Films. Bis zu 50 Entwürfe pro Konto; GET /v1/films/{id} liefert das vollständige Rezept, PATCH aktualisiert title oder data, DELETE entfernt den Entwurf und lässt seine Renders in der Bibliothek. Der Filmmodus des Studios speichert und lädt genau diese Entwürfe, ein per Skript angelegtes Rezept lässt sich also unter /studio/video öffnen und von Hand korrigieren – oder umgekehrt.

Schreib Szenen-Prompts so, wie die Engines sie mögen: ein fließender Absatz mit Motiv, Bewegung, Kamera, Licht und Stimmung. Den Rest liefert der Look; wiederhol nicht in jeder Szene „Film noir, 1960er“.

Alles mit einem Aufruf drehen

curl -X POST https://eroq.ai/v1/films/FILM_ID/render \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "store": true }'

Jede Szene mit Prompt wird zu einem asynchronen Video-Job – jeweils ein POST /v1/videos/generations, mit den Parametern des Looks zusammengeführt –, und der Aufruf antwortet mit 202 und einem Bericht pro Szene:

{
  "id": "FILM_ID",
  "scenes": [
    { "scene": 0, "id": "job-a…", "status": "processing" },
    { "scene": 1, "id": "job-b…", "status": "processing" },
    { "scene": 2, "id": "job-c…", "status": "processing" }
  ],
  "usage": { "credits_spent": 380, "credits_remaining": 5620 }
}

Szenen werden einzeln abgerechnet und der Reihe nach eingereiht; geht das Guthaben aus, stoppen die restlichen Szenen also sauber, statt halb abgerechnet zu werden. Eine Szene, die nicht eingereiht werden kann, meldet ihren Fehler an ihrer Stelle – eine gesperrte Engine antwortet zum Beispiel mit plan_required –, während die anderen weiterlaufen. Jede Szene, deren Render später fehlschlägt, wird automatisch erstattet.

Die Plan-Freigaben gelten für das model des Looks: Motion One steht jedem Konto zur Verfügung und ist die unzensierte Engine; Seedance, Kling, Hailuo und Veo werden vorgelagert von ihren Anbietern moderiert und brauchen den Plan, der sie freischaltet. Auch seconds pro Szene ist durch den Plan begrenzt (10, 15, 20 oder 30 s).

Die Jobs pollen

Jede eingereihte Szene ist ein ganz normaler Video-Job. Frag GET /v1/videos/generations/{id} alle paar Sekunden ab – kostenlos –, bis status den Wert succeeded oder failed hat.

const BASE = 'https://eroq.ai/v1'
const headers = { Authorization: `Bearer ${process.env.EROQ_API_KEY}` }

async function renderFilm(filmId) {
  const report = await fetch(`${BASE}/films/${filmId}/render`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ store: true }),
  }).then(r => r.json())

  const segments = []
  for (const scene of report.scenes.filter(s => s.status === 'processing')) {
    let job
    do {
      await new Promise(r => setTimeout(r, 4000))
      job = await fetch(`${BASE}/videos/generations/${scene.id}`, { headers }).then(r => r.json())
    } while (job.status === 'processing')
    if (job.status === 'succeeded') segments[scene.scene] = job.data[0].url
  }
  return segments.filter(Boolean)
}

Bei drei Szenen ist sequenzielles Polling in Ordnung; bei dreißig pollst du parallel oder abonnierst den Webhook video.generation.succeeded und sammelst die URLs, sobald sie eintreffen. So oder so hast du am Ende geordnete Clip-URLs, und genau die braucht das Veröffentlichen.

Mit Cover veröffentlichen

Zwei Aufrufe. Zuerst das Cover – Multipart, ein Bild bis 5 MB, kostenlos:

curl -X POST https://eroq.ai/v1/films/FILM_ID/cover \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -F "[email protected]"

Dann der Film selbst:

curl -X POST https://eroq.ai/v1/films/FILM_ID/publish \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rooftop night",
    "segments": ["https://…/scene-1.mp4", "https://…/scene-2.mp4", "https://…/scene-3.mp4"],
    "durationSeconds": 20
  }'

segments enthält 1 bis 24 geordnete URLs, und jede muss ein gehosteter Render aus deiner eigenen Bibliothek sein – fremde Medien werden abgelehnt. Der Film erscheint im Regal der Community als ein Eintrag, der die Segmente nacheinander abspielt, mit dem Cover auf der Karte und im Player. Zuschauer sehen Titel, Cover, Clips und Zähler; Prompts, Look und Besetzung bleiben privat. DELETE /v1/films/{id}/publish nimmt ihn wieder offline und behält Likes und Kommentare für eine erneute Veröffentlichung. Löschst du den Entwurf, verschwindet auch der Community-Eintrag – die Szenen-Renders bleiben in der Bibliothek.

Batches für Agenturen

Das Muster, das skaliert: ein Rezept pro Kunde als Vorlage, eine Schleife, die die Variablen austauscht, und ein Workspace, damit das ganze Team aus einem Guthaben schöpft.

• Varianten sind Rezepte. Dieselben drei Szenen in 16:9 für YouTube und 9:16 für Reels sind zwei Filme mit zwei Looks. Anlegen, rendern, pollen, ausliefern – bis zur Abnahme braucht es keinen Menschen.
• Kosten sind reine Rechnerei. Ein Motion-One-Film mit drei Szenen à 5, 5 und 10 Sekunden kostet 180 Credits, etwa $1.80 zum Preis des Einstiegspakets; die 20.000 monatlichen Credits des Studio-Plans reichen für ungefähr fünfzig davon, mit 4× Rate-Limits. Takes vervielfachen die Zahl, also entscheide, wie viele Alternativen die Abnahme wirklich braucht.
• Durchsatz gilt pro Schlüssel. Video-Anfragen sind pro Schlüssel begrenzt (6 pro Minute in der Basisstufe, multipliziert je nach Plan). Gib jeder Pipeline ihren eigenen Schlüssel, damit der Batch eines Kunden nie den eines anderen ausbremst.
• Charaktere reisen mit. Setz den wiederkehrenden Moderator eines Kunden in cast, und dasselbe Gesicht hält über Bild-zu-Video in jeder Szene – den größeren Workflow beschreibt die Seite für Agenturen.

Häufige Fragen

Was passiert, wenn eine Szene fehlschlägt?

Den anderen passiert nichts. Die fehlgeschlagene Szene wird automatisch erstattet; render sie einzeln mit POST /v1/videos/generations und denselben Look-Parametern neu und füg ihre URL dann in segments ein. Ein erneuter render-Aufruf auf den Film würde jede Szene neu drehen und neu abrechnen.

Kann ich einen Film rendern, den jemand im Studio gebaut hat?

Ja. GET /v1/films listet die Entwürfe, die der Filmmodus des Studios gespeichert hat; render jeden davon über seine ID.

Kostet das Veröffentlichen Credits?

Nein. Der Cover-Upload und der Publish-Aufruf sind kostenlos; bezahlt hast du die Szenen-Renders, und das ist alles.

Fang mit einem Rezept aus drei Szenen und den Gratis-Credits an – hol dir einen API-Schlüssel und dreh los.