API-Referenz

Überblick

Die öffentliche CyberBara API ist unter /api/v1 verfügbar und unterstützt:

Bild-Tasks generieren
Video-Tasks generieren
Referenzbilder hochladen und wiederverwendbare URLs erhalten
Task-Status und Ausgaben abfragen
Credits-Guthaben prüfen
Credit-Nutzung prüfen
Credits vor dem Erstellen eines Tasks schätzen
Öffentliche Modelle auflisten

Details zum Anbieter werden absichtlich nicht an Clients offengelegt.

Basis-URL

Verwende deine eigene bereitgestellte Domain.

https://<your-domain>

Beispiel:

https://cyberbara-preview.iamzerolu.workers.dev

Authentifizierung

Übermittle deinen API-Key in einem dieser Header:

Authorization: Bearer <API_KEY>

oder

x-api-key: <API_KEY>

Wenn der Key fehlt oder ungültig ist, gibt die API 401 zurück.

Antwortformat

Erfolg:

{
  "data": {}
}

Fehler:

{
  "error": {
    "code": "error_code",
    "message": "human readable message",
    "details": {}
  }
}

Modelle

`GET /api/v1/models`

Optionaler Query-Parameter:

media_type=image|video

Beispiel:

curl -X GET 'https://<your-domain>/api/v1/models?media_type=video' \
  -H 'Authorization: Bearer <API_KEY>'

Antwortbeispiel:

{
  "data": {
    "models": [
      {
        "model": "sora-2",
        "media_type": "video",
        "supported_scenes": ["text-to-video", "image-to-video"]
      },
      {
        "model": "kling-2.6",
        "media_type": "video",
        "supported_scenes": ["text-to-video", "image-to-video"]
      }
    ],
    "total": 2
  }
}

Fehlerbeispiel (invalid_media_type):

{
  "error": {
    "code": "invalid_media_type",
    "message": "media_type must be \"image\" or \"video\"."
  }
}

Uploads

`POST /api/v1/uploads/images`

Lade ein oder mehrere Referenzbilder hoch und verwende die zurückgegebenen URLs anschließend in options.image_input.

Anforderungen:

Content-Type: multipart/form-data
Feldname: files (oder file bei Einzelupload)
maximale Anzahl Dateien pro Request: 10
maximale Dateigröße: jeweils 10MB
unterstützte MIME-Typen: image/jpeg, image/jpg, image/png, image/webp, image/gif, image/svg+xml, image/avif, image/heic, image/heif

Beispiel:

curl -X POST 'https://<your-domain>/api/v1/uploads/images' \
  -H 'Authorization: Bearer <API_KEY>' \
  -F 'files=@./reference.png'

Antwortbeispiel:

{
  "data": {
    "files": [
      {
        "url": "https://cdn.example.com/uploads/api/v1/uploads/3e7e48e6/7f2f25f8d6c26f11b2a5bb6b3f7f4a28.png",
        "key": "api/v1/uploads/3e7e48e6/7f2f25f8d6c26f11b2a5bb6b3f7f4a28.png",
        "filename": "reference.png",
        "content_type": "image/png",
        "size": 245123,
        "deduped": false
      }
    ],
    "urls": [
      "https://cdn.example.com/uploads/api/v1/uploads/3e7e48e6/7f2f25f8d6c26f11b2a5bb6b3f7f4a28.png"
    ],
    "count": 1
  }
}

`POST /api/v1/uploads/videos`

Lade ein Referenzvideo hoch und verwende die zurückgegebenen URLs anschließend in options.video_input (oder in options.video_url für seedance-2-watermark-remover).

Anforderungen:

Content-Type: multipart/form-data
Feldname: files (oder file bei Einzelupload)
maximale Anzahl Dateien pro Request: 1
maximale Dateigröße: 50MB
unterstützte MIME-Typen: video/mp4, video/quicktime

Beispiel:

curl -X POST 'https://<your-domain>/api/v1/uploads/videos' \
  -H 'Authorization: Bearer <API_KEY>' \
  -F 'files=@./reference.mp4'

Antwortbeispiel:

{
  "data": {
    "files": [
      {
        "url": "https://cdn.example.com/uploads/api/v1/uploads/3e7e48e6/2d9b18f0b5a0a9b4c65b7f6c3b2f7c32.mp4",
        "key": "api/v1/uploads/3e7e48e6/2d9b18f0b5a0a9b4c65b7f6c3b2f7c32.mp4",
        "filename": "reference.mp4",
        "content_type": "video/mp4",
        "size": 1245123,
        "deduped": false
      }
    ],
    "urls": [
      "https://cdn.example.com/uploads/api/v1/uploads/3e7e48e6/2d9b18f0b5a0a9b4c65b7f6c3b2f7c32.mp4"
    ],
    "count": 1
  }
}

Fehlerbeispiel (invalid_file_type):

{
  "error": {
    "code": "invalid_file_type",
    "message": "Unsupported image type for file \"sample.pdf\".",
    "details": {
      "index": 0,
      "filename": "sample.pdf"
    }
  }
}

Beispiel für image-to-image mit einer Upload-URL:

{
  "model": "nano-banana-pro",
  "scene": "image-to-image",
  "prompt": "Keep composition, make it cinematic at night",
  "options": {
    "image_input": ["https://cdn.example.com/uploads/api/v1/uploads/...png"]
  }
}

Credits

`GET /api/v1/credits/balance`

Gibt das aktuelle Credits-Guthaben zurück.

curl -X GET 'https://<your-domain>/api/v1/credits/balance' \
  -H 'Authorization: Bearer <API_KEY>'

Antwortbeispiel:

{
  "data": {
    "user_id": "3e7e48e6-f2fa-4f66-abf8-db7a40eaf517",
    "remaining_credits": 44,
    "updated_at": "2026-03-03T04:08:19.320Z"
  }
}

Fehlerbeispiel (invalid_api_key):

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key."
  }
}

`POST /api/v1/credits/quote`

Schätze Credits, bevor du einen Task erstellst.

Request-Body:

model erforderlich
media_type optional, wenn das Modell es selbst ableiten kann
scene optional, aber empfohlen
options optional

curl -X POST 'https://<your-domain>/api/v1/credits/quote' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-pro",
    "media_type": "image",
    "scene": "text-to-image",
    "options": { "resolution": "1k" }
  }'

Antwortbeispiel:

{
  "data": {
    "model": "nano-banana-pro",
    "media_type": "image",
    "scene": "text-to-image",
    "estimated_credits": 8,
    "remaining_credits": 44,
    "can_afford": true,
    "pricing_rule": "nano-banana-pro",
    "fallback_pricing": false
  }
}

Fehlerbeispiel (unsupported_model):

{
  "error": {
    "code": "unsupported_model",
    "message": "Model is not supported."
  }
}

`GET /api/v1/credits/usage`

Query-Parameter:

page Standard 1
limit Standard 20, Maximum 100
from optional, ISO-Datetime oder YYYY-MM-DD
to optional, ISO-Datetime oder YYYY-MM-DD
Reine Datumswerte werden in UTC interpretiert (from -> 00:00:00.000Z, to -> 23:59:59.999Z)

curl -X GET 'https://<your-domain>/api/v1/credits/usage?page=1&limit=20&from=2026-03-01&to=2026-03-03' \
  -H 'Authorization: Bearer <API_KEY>'

Antwortbeispiel:

{
  "data": {
    "summary": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "total_pages": 1,
      "total_credits_consumed": 28,
      "from": "2026-03-03T00:00:00.000Z",
      "to": "2026-03-03T23:59:59.999Z"
    },
    "items": [
      {
        "id": "0a961844-e042-4a17-bf23-2a5f2680d375",
        "transaction_no": "79739092304928500",
        "credits_consumed": 20,
        "scene": "text-to-video",
        "description": "generate video",
        "media_type": "video",
        "task_id": "2fa99a50-fb96-407b-a562-82de8265f48e",
        "created_at": "2026-03-03T04:31:55.116Z"
      }
    ]
  }
}

Fehlerbeispiel (invalid_date):

{
  "error": {
    "code": "invalid_date",
    "message": "Invalid date format. Use ISO datetime or YYYY-MM-DD."
  }
}

Fehlerbeispiel (invalid_date_range):

{
  "error": {
    "code": "invalid_date_range",
    "message": "The \"from\" date must be earlier than the \"to\" date."
  }
}

Task-Erstellung

`POST /api/v1/images/generations`

Request-Body:

model erforderlich
prompt für die meisten Modelle erforderlich
scene optional (text-to-image / image-to-image)
options optional

curl -X POST 'https://<your-domain>/api/v1/images/generations' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "A cinematic portrait under neon rain",
    "scene": "text-to-image",
    "options": { "resolution": "1k" }
  }'

Die Antwort enthält deine interne Task-ID:

{
  "data": {
    "task_id": "uuid",
    "status": "pending",
    "media_type": "image",
    "model": "nano-banana-pro",
    "scene": "text-to-image",
    "credits": {
      "cost": 8,
      "remaining": 36
    },
    "created_at": "2026-03-03T04:29:12.612Z"
  }
}

Fehlerbeispiel (insufficient_credits):

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits."
  }
}

`POST /api/v1/videos/generations`

Request-Body:

model erforderlich
prompt für die meisten Videomodelle erforderlich (einschließlich seedance-*, kling-2.6, veo-*)
prompt ist für sora-2-pro auf API-Validierungsebene optional, wird aber weiterhin empfohlen
scene optional (text-to-video / image-to-video / video-to-video)
options optional

curl -X POST 'https://<your-domain>/api/v1/videos/generations' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "sora-2",
    "prompt": "A calm drone shot over snowy mountains at sunrise",
    "scene": "text-to-video",
    "options": { "duration": "10", "resolution": "standard" }
  }'

Antwortbeispiel:

{
  "data": {
    "task_id": "2fa99a50-fb96-407b-a562-82de8265f48e",
    "status": "pending",
    "media_type": "video",
    "model": "sora-2",
    "scene": "text-to-video",
    "credits": {
      "cost": 20,
      "remaining": 16
    },
    "created_at": "2026-03-03T04:31:55.116Z"
  }
}

Fehlerbeispiel (insufficient_credits):

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits."
  }
}

Modellspezifische Optionen (vollständige Matrix)

In diesem Abschnitt sind alle modellspezifischen Request-Optionen aufgeführt, die derzeit von der öffentlichen API unterstützt werden.

Allgemeine Request-Felder:

model erforderlich
prompt modellabhängig (siehe jeweiliges Modell unten)
scene optional, aber dringend empfohlen
options optionales Objekt

Szenen-Inferenz (wenn scene weggelassen wird):

Bild-API:
- options.image_input enthält mindestens eine URL -> image-to-image
- ansonsten -> text-to-image
Video-API:
- options.video_input enthält mindestens eine URL -> video-to-video
- sonst, wenn options.image_input mindestens eine URL enthält -> image-to-video
- ansonsten -> text-to-video

Gemeinsame Options-Felder:

Feld	Typ	Bedeutung
`options.image_input`	`string[]`	Eingabe-/Referenzbild-URLs
`options.video_input`	`string[]`	Eingabe-/Referenzvideo-URLs

Hinweise:

Die öffentliche API akzeptiert nur options.*-Felder. Sende keine anbieterinternen Keys wie image_url, image_urls, input_images oder imageUrls (außer options.video_url für seedance-2-watermark-remover).
Für alle unten aufgeführten Modelle gilt: Wenn sowohl prompt als auch options leer sind, gibt die API invalid_request zurück.
Einige Modelle validieren Optionen strikt, andere reichen Optionen mit minimaler oder ohne Validierung an den Modell-Endpoint weiter.
Unbekannte Optionen werden bei strikt validierten Modellen ignoriert; bei Pass-through-Modellen werden sie weitergeleitet.

Bildmodelle

`nano-banana-2`

Unterstützte Szenen: text-to-image, image-to-image. Validierungsstufe: Strikte Schlüssel + leichte Normalisierung.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Für beide Szenen erforderlich
`options.image_input`	`string[]`	Für `image-to-image` nötig	URL-Array	Wenn vorhanden und nicht leer, kann die Szene als `image-to-image` abgeleitet werden
`options.aspect_ratio`	`string`	Nein	jeder nicht leere String	Wird unverändert weitergereicht
`options.resolution`	`string`	Nein	normalisiert: `1K` / `2K` / `4K`	Eingaben wie `1k`, `2k`, `4k` werden normalisiert; andere Strings werden weitergereicht
`options.output_format`	`string`	Nein	normalisiert: `jpg` / `png`	`jpeg` wird zu `jpg`; andere Strings werden weitergereicht
`options.google_search`	`boolean`	Nein	standardmäßig nicht gesetzt	Nur von `nano-banana-2` unterstützt

`nano-banana-pro`

Unterstützte Szenen: text-to-image, image-to-image. Validierungsstufe: Strikte Schlüssel + leichte Normalisierung.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Für beide Szenen erforderlich
`options.image_input`	`string[]`	Für `image-to-image` nötig	URL-Array	Wenn vorhanden und nicht leer, kann die Szene als `image-to-image` abgeleitet werden
`options.aspect_ratio`	`string`	Nein	jeder nicht leere String	Wird unverändert weitergereicht
`options.resolution`	`string`	Nein	normalisiert: `1K` / `2K` / `4K`	Eingaben wie `1k`, `2k`, `4k` werden normalisiert; andere Strings werden weitergereicht
`options.output_format`	`string`	Nein	normalisiert: `jpg` / `png`	`jpeg` wird zu `jpg`; andere Strings werden weitergereicht

Mit Ausnahme von kling-video-o1, seedance-2-preview, seedance-2-fast-preview und seedance-2-watermark-remover unterstützen die folgenden Modelle kein video-to-video. Daher sollte options.video_input nicht gesendet werden.

`sora-2`

Unterstützte Szenen: text-to-video, image-to-video. Validierungsstufe: Strikt.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Für beide Szenen erforderlich
`options.image_input`	`string[]`	Für `image-to-video` nötig	URL-Array	Als Bildreferenzen verwendet
`options.aspect_ratio`	`string`	Nein	`landscape` / `portrait` (Standard `landscape`)	Streng validiert
`options.duration` / `options.n_frames`	`string` oder `number`	Nein	`10` / `15` (Standard `10`)	Streng validiert
`options.remove_watermark`	`boolean`	Nein	Standard `true`	Streng validiert
`options.upload_method`	`string`	Nein	`s3` / `oss` (Standard `s3`)	Streng validiert

`sora-2-pro`

Unterstützte Szenen: text-to-video, image-to-video. Validierungsstufe: Strikt.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Nein für API-Validierung	optional	Empfohlen
`options.image_input`	`string[]`	Für `image-to-video` nötig	URL-Array	Als Bildreferenzen verwendet
`options.aspect_ratio`	`string`	Nein	`landscape` / `portrait` (Standard `landscape`)	Streng validiert
`options.duration` / `options.n_frames`	`string` oder `number`	Nein	`10` / `15` (Standard `10`)	Streng validiert
`options.resolution` / `options.size`	`string`	Nein	`standard` / `high` (Standard `standard`)	Streng validiert

`seedance-2-preview`

Unterstützte Szenen: text-to-video, image-to-video, video-to-video. Validierungsstufe: Strikt.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Für alle Szenen erforderlich
`options.image_input`	`string[]`	Für `image-to-video` nötig	URL-Array (max. 9)	Kann im Prompt als Bildreferenz verwendet werden (`@image1`, `@image2`, ...)
`options.video_input`	`string[]`	Für `video-to-video` nötig	einzelne URL	Seedance-2.0-Videobearbeitungsmodus. Genau eine URL.
`options.duration`	`string` oder `number`	Nein (für `video-to-video` ignoriert)	`5` / `10` / `15` (Standard `5`)	Im Videobearbeitungsmodus entspricht die Ausgabelänge der Länge des Eingabevideos.
`options.aspect_ratio`	`string`	Nein	`16:9` / `9:16` / `4:3` / `3:4` (Standard `16:9`)	Das Seitenverhältnis ist Best Effort; das Bildverhältnis der Referenzbilder kann es überschreiben
`options.parent_task_id`	`string`	Nein	Task-ID	Erweiterung eines früheren Seedance-2.0-Tasks; fehlende Felder können vom Parent geerbt werden

`seedance-2-fast-preview`

Unterstützte Szenen: text-to-video, image-to-video, video-to-video. Validierungsstufe: Strikt.

Die Felder entsprechen seedance-2-preview.

`seedance-2-watermark-remover`

Unterstützte Szenen: video-to-video. Validierungsstufe: Strikt.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Nein	optional	Wird vom Watermark Remover nicht verwendet
`options.video_input`	`string[]`	Ja	einzelne URL	Zu verarbeitende Video-URL
`options.video_url`	`string`	Ja	einzelne URL	Alternative zu `options.video_input`
`options.duration`	`string` oder `number`	Nein	automatisch erkannt	Optionaler Hinweis; wenn weggelassen, erkennt der Prozessor die Dauer automatisch

`seedance-1-pro`

Unterstützte Szenen: text-to-video, image-to-video. Validierungsstufe: Strikt + partielle Durchleitung bei einigen Strings.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Für beide Szenen erforderlich
`options.image_input`	`string[]`	Für `image-to-video` nötig	erste Bild-URL wird verwendet	`image-to-video` erfordert mindestens ein Bild
`options.resolution`	`string`	Nein	Standard `720p`	Empfohlen: `480p`, `720p`, `1080p`
`options.duration`	`string` oder `number`	Nein	Standard `5`	Empfohlen: `5`, `10`
`options.aspect_ratio`	`string`	Nein	Standard `16:9`	Wird für `text-to-video` genutzt; `image-to-video` ignoriert dieses Feld
`options.camera_fixed`	`boolean`	Nein	standardmäßig nicht gesetzt	Unterstützt
`options.seed` / `options.seeds`	`integer`	Nein	`-1` bis `2147483647`	Strenge Bereichsprüfung
`options.enable_safety_checker`	`boolean`	Nein	standardmäßig nicht gesetzt	Unterstützt

`seedance-1-lite`

Unterstützte Szenen: text-to-video, image-to-video. Validierungsstufe: Strikt + partielle Durchleitung bei einigen Strings.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Für beide Szenen erforderlich
`options.image_input`	`string[]`	Für `image-to-video` nötig	erste Bild-URL wird verwendet	Wenn ein zweites Bild vorhanden ist, wird es automatisch als `end_image_url` genutzt
`options.resolution`	`string`	Nein	Standard `720p`	Empfohlen: `480p`, `720p`, `1080p`
`options.duration`	`string` oder `number`	Nein	Standard `5`	Empfohlen: `5`, `10`
`options.aspect_ratio`	`string`	Nein	Standard `16:9`	Wird für `text-to-video` genutzt; `image-to-video` ignoriert dieses Feld
`options.camera_fixed`	`boolean`	Nein	standardmäßig nicht gesetzt	Unterstützt
`options.seed` / `options.seeds`	`integer`	Nein	`-1` bis `2147483647`	Strenge Bereichsprüfung
`options.enable_safety_checker`	`boolean`	Nein	standardmäßig nicht gesetzt	Nur für `text-to-video` unterstützt
`options.end_image_url`	`string`	Nein	URL	Für `image-to-video` unterstützt

`seedance-1-pro-fast`

Unterstützte Szenen: image-to-video. Validierungsstufe: Strikt + partielle Durchleitung bei einigen Strings.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Erforderlich
`options.image_input`	`string[]`	Ja	erste Bild-URL wird verwendet	Erforderlich
`options.resolution`	`string`	Nein	Standard `720p`	Empfohlen: `720p`, `1080p`
`options.duration`	`string` oder `number`	Nein	Standard `5`	Empfohlen: `5`, `10`

`kling-2.6`

Unterstützte Szenen: text-to-video, image-to-video. Validierungsstufe: Strikt.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Für beide Szenen erforderlich
`options.image_input`	`string[]`	Für `image-to-video` nötig	URL-Array	`image-to-video` erfordert mindestens ein Bild
`options.duration`	`string` oder `number`	Nein	`5` / `10` (Standard `5`)	Streng validiert
`options.sound`	`boolean`	Nein	Standard `false`	Streng validiert
`options.aspect_ratio`	`string`	Nein	`1:1` / `16:9` / `9:16` (Standard `16:9`)	Wird für `text-to-video` genutzt; `image-to-video` ignoriert dieses Feld

`veo-3.1-fast`

Unterstützte Szenen: text-to-video, image-to-video. Validierungsstufe: Strikt.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Erforderlich
`options.image_input`	`string[]`	Bedingt	URL-Array	Hängt von den `generationType`-Regeln unten ab
`options.generationType`	`string`	Nein	`TEXT_2_VIDEO` / `FIRST_AND_LAST_FRAMES_2_VIDEO` / `REFERENCE_2_VIDEO`	Wenn weggelassen, wird anhand der Anzahl von `image_input` automatisch abgeleitet
`options.aspect_ratio`	`string`	Nein	`16:9` / `9:16` / `Auto` (Standard `16:9`)	`landscape` -> `16:9`, `portrait` -> `9:16`; `REFERENCE_2_VIDEO` erlaubt nur `16:9`
`options.seed` / `options.seeds`	`integer`	Nein	`10000` bis `99999`	Strenge Bereichsprüfung
`options.enableTranslation`	`boolean`	Nein	standardmäßig nicht gesetzt	Optional
`options.watermark`	`string`	Nein	jeder nicht leere String	Optional

Regeln:

TEXT_2_VIDEO: image_input muss leer sein
FIRST_AND_LAST_FRAMES_2_VIDEO: image_input muss 1-2 Bilder enthalten
REFERENCE_2_VIDEO: image_input muss 1-3 Bilder enthalten

`veo-3.1-quality`

Unterstützte Szenen: text-to-video, image-to-video. Validierungsstufe: Strikt.

Die Felder entsprechen veo-3.1-fast, mit folgender Ausnahme:

options.generationType=REFERENCE_2_VIDEO wird nicht unterstützt

`kling-video-o1`

Unterstützte Szenen: video-to-video. Validierungsstufe: Pass-through.

Feld	Typ	Erforderlich	Erlaubt / Standard	Hinweise
`prompt`	`string`	Ja	nicht leer	Erforderlich
`options.video_input`	`string[]`	In der Praxis nötig	erste Video-URL wird verwendet	Wenn `scene` fehlt, hilft ein nicht leeres `video_input`, `video-to-video` abzuleiten
`options.image_input`	`string[]`	Nein	URL-Array	Optionale Referenzbilder
`options.*`	`any`	Nein	anbieterdefiniert	Alle zusätzlichen Keys werden weitergereicht

kling-video-o1 ist ein Pass-through-Modell. Neben options.video_input können weitere anbieterdefinierte Felder unter options.* erforderlich sein.

Schnelle Zuordnung von Szene und Optionen

Bildgenerierung:

text-to-image: in der Regel nur prompt
image-to-image: options.image_input einschließen

Videogenerierung:

text-to-video: immer prompt einschließen
image-to-video: options.image_input einschließen; bei den meisten Modellen zusätzlich prompt
video-to-video: options.video_input einschließen; prompt einschließen, wenn das gewählte Modell es verlangt

Wenn du deterministisches Routing möchtest, übergib scene immer explizit.

Task-Abfrage

`GET /api/v1/tasks/{taskId}`

Frage diesen Endpoint ab, bis der Task einen Endstatus erreicht.

curl -X GET 'https://<your-domain>/api/v1/tasks/<TASK_ID>' \
  -H 'Authorization: Bearer <API_KEY>'

Antwortbeispiel (pending):

{
  "data": {
    "task": {
      "id": "2fa99a50-fb96-407b-a562-82de8265f48e",
      "status": "pending",
      "media_type": "video",
      "model": "sora-2",
      "scene": "text-to-video",
      "prompt": "A cinematic wide shot of waves hitting black volcanic beach at sunrise",
      "credits": { "cost": 20 },
      "output": { "images": [], "videos": [] },
      "created_at": "2026-03-03T04:31:55.116Z",
      "updated_at": "2026-03-03T04:32:08.511Z"
    }
  }
}

Fehlerbeispiel (task_not_found):

{
  "error": {
    "code": "task_not_found",
    "message": "Task not found."
  }
}

Statuswerte:

pending
processing
success
failed
canceled

Erfolgreiche Antworten enthalten Media-URLs unter:

data.task.output.images
data.task.output.videos

Beispiele für Task-Ausgaben

Erfolgreicher Bild-Task:

{
  "data": {
    "task": {
      "id": "20b061f3-d051-4795-b355-856325d08f7c",
      "status": "success",
      "media_type": "image",
      "model": "nano-banana-pro",
      "scene": "text-to-image",
      "prompt": "A cinematic portrait under neon rain",
      "credits": { "cost": 8 },
      "output": {
        "images": [
          "https://static.nanobananaproprompts.com/cyberbara_uploads/kie/image/21075dc0-7968-46fd-93fe-e366f558325b.png"
        ],
        "videos": []
      },
      "created_at": "2026-03-03T04:29:12.612Z",
      "updated_at": "2026-03-03T04:29:31.475Z"
    }
  }
}

Erfolgreicher Video-Task:

{
  "data": {
    "task": {
      "id": "2fa99a50-fb96-407b-a562-82de8265f48e",
      "status": "success",
      "media_type": "video",
      "model": "sora-2",
      "scene": "text-to-video",
      "prompt": "A cinematic wide shot of waves hitting black volcanic beach at sunrise",
      "credits": { "cost": 20 },
      "output": {
        "images": [],
        "videos": [
          "https://static.nanobananaproprompts.com/cyberbara_uploads/kie/video/b55bf86d-e3a3-4b81-ae28-a1cff40a71db.mp4"
        ]
      },
      "created_at": "2026-03-03T04:31:55.116Z",
      "updated_at": "2026-03-03T04:34:22.836Z"
    }
  }
}

Fehlgeschlagener Task:

{
  "data": {
    "task": {
      "id": "341ab8cd-1296-4a5d-968a-cccf60c9caab",
      "status": "failed",
      "media_type": "video",
      "model": "sora-2",
      "scene": "text-to-video",
      "prompt": "A calm drone shot over snowy mountains at sunrise",
      "credits": { "cost": 20 },
      "output": {
        "images": [],
        "videos": []
      },
      "created_at": "2026-03-03T04:30:18.041Z",
      "updated_at": "2026-03-03T04:31:01.420Z"
    }
  }
}

Empfohlener Ablauf

GET /api/v1/models aufrufen
Falls nötig POST /api/v1/uploads/images für Referenz-URLs aufrufen
POST /api/v1/credits/quote aufrufen
Über den Endpoint für Bild- oder Videogenerierung einen Task erstellen
GET /api/v1/tasks/{taskId} pollen, bis ein Endstatus erreicht ist
Abrechnungswirkung über GET /api/v1/credits/usage prüfen

Häufige Fehlercodes (nicht abschließend)

api_key_required
invalid_api_key
too_many_requests
invalid_json
invalid_multipart
invalid_date
invalid_date_range
files_required
too_many_files
invalid_file_type
invalid_file_size
file_too_large
invalid_model
unsupported_model
invalid_model_for_media_type
invalid_scene
scene_not_supported
invalid_media_type
invalid_request
service_unavailable
insufficient_credits
upload_failed
generation_failed
invalid_task_id
task_not_found
task_not_ready
query_failed
internal_error

API-Referenz

Auf dieser Seite