A-Roll automatisieren

01 · Schnellstart

Vom Key zum laufenden Auftrag

Erstelle unter „Konto“ einen benannten Key. Das vollständige Geheimnis wird genau einmal angezeigt. Speichere es als Server-Secret und sende es als Bearer-Token. Halte keine minutenlange Verbindung offen; poll den Status stattdessen mit exponentiellem Backoff.

# 1. Nur prüfen – noch kein Auftrag und keine Abbuchung
curl -X POST https://aroll-studio.de/v1/jobs/validate \
  -H "Authorization: Bearer $AROLL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @job.json

# 2. Idempotenten Uploadentwurf erstellen
curl -X POST https://aroll-studio.de/v1/jobs \
  -H "Authorization: Bearer $AROLL_API_KEY" \
  -H "Idempotency-Key: agentur-projekt-42-v1" \
  -H "Content-Type: application/json" \
  --data-binary @job.json

# 3. Jede zurückgegebene Uploadanweisung unverändert ausführen
curl -X PUT "<uploads[i].url>" \
  -H "content-type: <uploads[i].headers.content-type>" \
  -H "cache-control: max-age=3600" \
  -H "x-upsert: false" \
  --data-binary @moderation.wav

# 4. Finalisieren – Uploads prüfen, Credits buchen, normal einreihen
curl -X POST https://aroll-studio.de/v1/jobs/<job_id>/finalize \
  -H "Authorization: Bearer $AROLL_API_KEY"

# 5. Status mit Backoff pollen
curl https://aroll-studio.de/v1/jobs/<job_id> \
  -H "Authorization: Bearer $AROLL_API_KEY"

Ein stabiler Idempotency-Key gehört dauerhaft zu genau einem unveränderten Auftragsplan. Wiederholungen liefern denselben Auftrag und buchen nicht doppelt ab.

02 · Auftragsplan

Quellen und gewünschte Pakete festlegen

Für script_guided sind mindestens zwei Quellen und script_texterforderlich. Standardmäßig ist Studio Standard ausgewählt und verhält sich wie der bisherige A-Roll-Weg, mit etwas sanfterem Debreath. Mitdeliverables kannst du Final Cut, DaVinci, Premiere oder Enhanced Audio einzeln bestellen.

{
  "schema": "a_roll_public_job_v2",
  "title": "Moderation Folge 42",
  "language": "de",
  "deliverables": ["premiere"],
  "include_enhanced_audio": true,
  "composition": { "mode": "source_order" },
  "settings": {},
  "sources": [{
    "mode": "audio_only",
    "display_name": "Moderation",
    "audio_processing": {
      "schema": "a_roll_source_audio_policy_v1",
      "mode": "enhanced",
      "profile": { "kind": "builtin", "key": "studio_standard", "name": "Studio Standard", "revision": 1 },
      "settings": {
        "schema": "a_roll_audio_processing_settings_v1",
        "denoise_method": "speech_isolation",
        "noise_reduction_db": 12,
        "reverb_reduction_db": 12,
        "breath_reduction_db": 18,
        "leveler_strength": 50,
        "auto_eq": true
      }
    },
    "audio": {
      "file_name": "moderation.wav",
      "size_bytes": 4800044,
      "sha256": "<64 hex>",
      "duration_seconds": 50,
      "mime_type": "audio/wav",
      "browser_metadata": {
        "duration_source": "browser_metadata",
        "file_size_bytes": 4800044,
        "user_confirmed": false
      }
    }
  }]
}

03 · Video und Timecode

Originalvideo bleibt lokal

Das Originalvideo wird nicht hochgeladen. Dein System muss deshalb die echte Dateiidentität und den vollständigen technischen Sidecar liefern. Framerates dürfen nicht gerundet und Timecodes nicht erfunden werden. Lade bei integriertem Ton die tatsächlich aus diesem Video extrahierte Audiospur hoch; bei externer Audio zusätzlich den Kamerareferenzton.

{
  "file_name": "kamera-100fps.mp4",
  "file_size_bytes": 4000000,
  "sha256": "<64 hex>",
  "last_modified_unix_ms": 1785326400000,
  "expected_relative_path": "MEDIEN_HIER_ABLEGEN/kamera-100fps.mp4",
  "video_spec": {
    "frame_rate": "100",
    "duration_frames": 3000,
    "duration_seconds": 30,
    "width": 3840,
    "height": 2160,
    "start_timecode": "00:00:00:00",
    "timecode_detection_status": "absent",
    "timecode_needs_manual_review": false,
    "duration_source": "browser_metadata",
    "duration_frame_source": "cfr_duration_rounding",
    "dimensions_source": "browser_metadata",
    "file_name": "kamera-100fps.mp4",
    "file_size_bytes": 4000000,
    "fingerprint": "<derselbe Video-SHA-256>",
    "user_confirmed": false
  }
}

Das Beispiel zeigt die Mindestform, nicht einen Ersatz für echte Medienanalyse. Verwende die gemessenen Werte deiner Datei einschließlich Trackauswahl, Drop-Frame-Status, Dauerprovenienz und Timecode-Provenienz. /validate lehnt widersprüchliche Angaben ab.

04 · Downloads

Erst nach succeeded abrufen

Rufe danach GET /v1/jobs/<job_id>/deliverables auf. Intern werden drei Editorpakete und – sobald mindestens eine Quelle verbessert wird – zusätzlich ein Audio-Paket gemeinsam unter derselben delivery_set_id geprüft; ausgegeben wird nur deine Auswahl. Downloadanweisungen können eine URL, geordnete Chunks oderclient_composite_zip_v1 enthalten.

Der vorgeschlagene ZIP-Name beginnt mit dem bereinigten Namen der ersten primären Projektdatei. Das ist ausschließlich eine Downloaddarstellung; Paketbytes, Prüfsumme, XMLs und Referenzen auf MEDIEN_HIER_ABLEGEN/ bleiben unverändert.

Die Ergebnisse stehen normalerweise 72 Stunden zum Download bereit.

05 · Fehler und Support

Fehler sind maschinenlesbar

Jede Antwort enthält eine request_id. Gib sie bei technischen Fehlern zusammen mit der Auftrags-ID über die Kontaktseite an. Ein einzelner Beta-Fehler stoppt andere API- oder Website-Aufträge nicht.

06 · Sicherheit und Grenzen

Keys gehören niemals in Browser oder Apps

• Maximal drei aktive Keys pro Konto; jeden Key separat benennen und widerrufen.
• 60 Schreib-, 300 Lese- und 300 Downloadanfragen pro Key und Minute.
• Maximal zehn offene Uploadentwürfe pro Konto.
• Uploadrechte sind pfadgebunden, zwei Stunden gültig und erneuerbar.
• API-Aufträge verwenden dieselben Credits und bis zu sechs gemeinsame Worker-Slots.
• Key, signierte URLs und vollständige Metadatenpläne niemals protokollieren.