Wenn Sie Videoworkflows auf Seedance 2.0 oder 2.0-Fast erstellen, ist die Asset Library der Ort, an dem Sie Referenzmedien — Bilder, Videos und Audio — sauber in Ihre Generierungen einbinden. Anstatt bei jedem Aufruf Rohdaten zu übergeben, registrieren Sie eine Datei einmalig. Atlas validiert und verarbeitet sie vor, und Sie referenzieren sie anschließend über eine stabile ID für beliebig viele Generierungen.
Dieser Leitfaden führt Sie in drei cURL-Aufrufen von null zu einer funktionierenden Referenz.
Was die Asset Library ist (und was sie nicht ist)
Es handelt sich um einen verwalteten Medienspeicher für die Videogenerierung mit Seedance 2.0 / 2.0-Fast. Sie registrieren ein Asset, es wird vorverarbeitet, und sobald es auf „Active“ steht, referenzieren Sie es in Ihrer Generierungsanfrage als asset://<asset_id>.
Zwei Punkte vorab, die Ihnen Zeit beim Debugging sparen:
- Video und Audio müssen hier zuerst registriert werden. Sie können nicht inline als URLs in einer Generierungsanfrage übergeben werden. Nur Bilder können inline verwendet werden. Für jeden Workflow mit Video- oder Audioreferenz ist die Asset Library also der erforderliche Einstiegspunkt, keine optionale Annehmlichkeit.
- Upload nur über öffentliche URLs. Base64 / Data-URLs werden nicht unterstützt. Die Datei muss bei der Registrierung unter einer öffentlich erreichbaren URL liegen.
Bevor Sie beginnen
Sie benötigen einen Atlas Cloud API-Key aus dem Dashboard.
Ein Detail, das oft zu Problemen führt: Die Asset Library und die Generierungs-API liegen auf unterschiedlichen Hosts.
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Funktion | Host | Basis-URL |
|---|---|---|
| Asset Library (registrieren, pollen, verwalten) | console | https://console.atlascloud.ai/api/v1 |
| Videogenerierung | api | https://api.atlascloud.ai/api/v1 |
Beide verwenden denselben Auth-Header:
plaintext1export ATLASCLOUD_API_KEY="ihr-api-key-hier"
plaintext1Authorization: Bearer $ATLASCLOUD_API_KEY
Der Drei-Schritte-Ablauf
Registrieren → pollen bis „Active“ → in der Generierung referenzieren.
Schritt 1 — Ein Asset registrieren
Geben Sie Atlas eine öffentliche URL an. Setzen Sie den Typ auf Image, Video oder Audio (Standard ist Image).
plaintext1curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "type": "Video", 6 "url": "https://your-public-host.com/reference-clip.mp4" 7 }'
Die Antwort enthält die id des Assets und den Status Processing.
Es sieht dann in etwa so aus:
Notieren Sie sich die id (oben hervorgehoben) – diese werden Sie pollen und referenzieren.
Kurzer Hinweis: Was zählt als "öffentliche URL"?
Dies ist der Schritt, der am häufigsten falsch gemacht wird, daher ist Präzision wichtig. Atlas ruft Ihre Datei per einfachem HTTP GET auf die URL ab. Diese URL muss direkt die Rohdatei zurückgeben – kein Login, keine Cookies, keine „Klicken zum Ansehen“-Seite, kein JavaScript zum Rendern.
Der Schnelltest: Öffnen Sie die URL in einem privaten/Inkognito-Tab. Wenn das Bild angezeigt wird oder das Video ohne Anmeldung heruntergeladen wird, kann Atlas darauf zugreifen. Wenn Sie eine Viewer-Seite, eine Anmeldeaufforderung oder eine Vorschau-UI sehen, wird es nicht funktionieren.
Das bedeutet, dass Google Photos- oder Google Drive-Freigabelinks nicht funktionieren. Diese Links führen zu einer Webseite, die Ihr Medium hinter Googles Auth- und Umleitungssystem anzeigt – nicht zur Datei selbst. Atlas würde das Seiten-Wrapper-Element abrufen, nicht das Medium.
Was stattdessen funktioniert:
- Objektspeicher mit Public-Read-Zugriff oder Presigned URL — Amazon S3, Google Cloud Storage, Cloudflare R2, Azure Blob. Presigned URLs sind ideal: öffentlich, aber zeitlich begrenzt.
- Ein CDN oder Ihr eigener Webserver, der die Datei direkt ausliefert.
- Atlas' eigener Upload-Endpunkt — falls Sie nur eine lokale Datei haben (oder etwas aus Google Photos exportiert haben), laden Sie es zuerst zu Atlas hoch, um eine öffentliche storage.atlascloud.ai URL zu erhalten, und registrieren Sie dann diese URL:
plaintext1# Lokale Datei hochladen → gibt eine öffentliche storage.atlascloud.ai URL zurück 2curl -X POST "https://api.atlascloud.ai/api/v1/model/uploadMedia" \ 3 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 4 -F "file=@./reference-clip.mp4"
Nehmen Sie die download_url aus dieser Antwort und verwenden Sie sie als url bei der Registrierung des Assets in Schritt 1.
Schritt 2 — Pollen bis „Active“
Atlas validiert und verarbeitet die Datei. Pollen Sie das Asset, bis sein Status auf Active wechselt. (Dieser Endpunkt prüft automatisch den Upstream-Job, solange er noch auf Processing steht.)
plaintext1curl "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
Der Lebenszyklus sieht so aus:
plaintext1Create → Processing → Active → (bereit zur Verwendung) 2 ↓ 3 Failed → error_code / error_message prüfen
Wenn Sie Failed erhalten, geben error_code und error_message Aufschluss über die Ursache – meistens liegt es an Format-, Größen-, Dauer- oder Dimensionslimits. Beachten Sie die Anforderungstabellen unten, bevor Sie eine erneute Registrierung versuchen.
Gelegentlich sehen Sie Fehler wegen Richtlinienverstößen wie unten – das liegt daran, dass das Asset wahrscheinlich Sicherheitsvorgaben (Guardrails) verletzt. Wenn Sie überzeugt sind, dass das Asset keine Regeln verletzt oder Sie selbst der Urheberrechtsinhaber sind, kontaktieren Sie uns bitte zur Klärung!
Schritt 3 — In einer Generierung referenzieren
Sobald das Asset Active ist, übergeben Sie asset://<asset_id> in das passende Feld Ihrer Seedance-Anfrage — image, last_image, reference_images, reference_video oder reference_audio, je nach Endpunkt.
Beachten Sie hier den Host-Wechsel: Die Generierung erfolgt auf api.atlascloud.ai.
plaintext1curl -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "model": "bytedance/seedance-2.0/image-to-video", 6 "input": { 7 "prompt": "Ein cineastischer Dolly-Shot, warmes Sonnenuntergangslicht", 8 "image": "asset://<asset_id>" 9 } 10 }'
Dies gibt eine prediction id zurück. Pollen Sie diese für das fertige Video:
plaintext1curl "https://api.atlascloud.ai/api/v1/model/prediction/<prediction_id>" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
Wenn der Status completed (oder succeeded) lautet, finden Sie die Ergebnis-URL unter outputs.
Das ist der gesamte Ablauf. Der Sinn des Assets ist die Wiederverwendung: einmal registrieren, das gleiche asset://<asset_id> über so viele Generierungen hinweg verwenden, wie Sie benötigen.
Assets verwalten
Die Library bietet Ihnen volle Kontrolle über den Lebenszyklus.
plaintext1# Listen Sie Ihre Assets auf (paginiert, unterstützt Filter) 2curl "https://console.atlascloud.ai/api/v1/sd/assets" \ 3 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 4 5# Asset umbenennen 6curl -X PUT "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 7 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 8 -H "Content-Type: application/json" \ 9 -d '{ "name": "sunset-reference-v2" }' 10 11# In den Papierkorb verschieben (wiederherstellbar — dies ist ein Soft-Delete) 12curl -X DELETE "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 13 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 14 15# Papierkorb auflisten 16curl "https://console.atlascloud.ai/api/v1/sd/assets/trash" \ 17 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 18 19# Aus dem Papierkorb wiederherstellen 20curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>/restore" \ 21 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
Das Löschen ist designbedingt wiederherstellbar — Assets landen im Papierkorb und können wiederhergestellt werden, sodass ein versehentlicher Aufruf nicht zum Verlust des Assets führt.
Anforderungen an die Eingabe
Die Validierung erfolgt bei der Registrierung. Eine fehlerhafte Datei schlägt also bereits hier fehl, bevor Sie einen Generierungsaufruf verschwenden. Halten Sie diese Limits ein, um einen Failed-Status zu vermeiden.
Bild
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Eigenschaft | Limit |
|---|---|
| Formate | jpeg, png, webp, bmp, tiff, gif, heic/heif |
| Seitenverhältnis (B/H) | 0.4 – 2.5 |
| Breite / Höhe | 300 – 6000 px |
| Größe | < 30 MB |
Video
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Eigenschaft | Limit |
|---|---|
| Formate | mp4, mov |
| Auflösung | 480p, 720p |
| Dauer | 2 – 15 s |
| Seitenverhältnis (B/H) | 0.4 – 2.5 |
| Breite / Höhe | 300 – 6000 px |
| Gesamtpixel (B×H) | 409.600 – 927.408 (z. B. 640×640 bis 834×1112) |
| Größe | ≤ 50 MB |
| FPS | 24 – 60 |
Audio
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Eigenschaft | Limit |
|---|---|
| Formate | wav, mp3 |
| Dauer | 2 – 15 s |
| Größe | ≤ 15 MB |
Fehlercodes
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Code | Bedeutung |
|---|---|
| 200 | Erfolg |
| 400 | Ungültige Anfrage |
| 401 | Fehlender oder ungültiger API-Key |
| 404 | Asset nicht gefunden |
| 500 | Serverfehler |
Wichtige Hinweise
- Video und Audio müssen vorab registriert werden. Nur Bilder können inline übergeben werden. Überspringen Sie die Registrierung bei Video/Audio, hat die Generierung keine Referenz.
- Nur URL, kein Base64. Die Quelldatei muss bei der Registrierung unter einer öffentlichen URL liegen.
- Zwei Hosts. Assets auf console.atlascloud.ai; Generierung auf api.atlascloud.ai. Das Vertauschen ist der häufigste Grund für 404 / 401 Fehler.
- Validieren vor Generieren. Fehlerhafte Eingaben schlagen bei der Registrierung fehl, nicht mitten in der Generierung — genau das ist der Zweck. Prüfen Sie vorher die Anforderungstabellen.
