Medien

Referenzbilder, -videos und -audio per URL, eingebettet oder per Upload senden – und die Dateien herunterladen, die ein Task erzeugt.

Viele Modelle nehmen Dateien als Eingabe – ein Foto zum Animieren, einen Clip zum Verlängern, eine Stimmprobe, einen Song. Es gibt vier Wege, eine Datei zu übergeben, und einen, Ergebnisse zurückzubekommen.

Vier Wege, eine Datei zu senden

Du hast	Sende es als	Am besten für
Einen öffentlichen HTTPS-Link	Die URL selbst, z. B. `"image_url": "https://…/photo.jpg"`	Dateien, die du schon hostest
Ein kleines Bild im Speicher	Eine Data-URI, z. B. `"image_url": "data:image/png;base64,…"`	Schnelle Tests, Bilder unter 1 MiB
Eine lokale Datei	Einen Upload, dann `"image_url": "popnow://f/fil_…"`	Alles andere, auch Video und Audio
Eine Datei aus deiner Asset-Bibliothek	`"image_url": "popnow://a/ast_…"`	Dateien, die du in vielen Tasks wiederverwendest. Siehe Assets

Egal welchen Weg du nimmst: Die Datei gehört in das Feld, das das Schema des Modells dafür vorsieht (image_url, image_urls, video_url, audio_url …).

Öffentliche Links

Der Link muss die Datei selbst liefern und während der Task läuft ohne Anmeldung erreichbar bleiben. Eine Freigabeseite aus einem Cloud-Speicher oder sozialen Netzwerk liefert eine Webseite statt der Datei, und der Task scheitert mit invalid_asset; lade die Datei dann herunter und lade sie hoch.

Eingebettete Bilder

Bilder lassen sich als Standard-Base64-Data-URI mit MIME-Typ senden: JPEG, PNG, WebP oder GIF, je höchstens 1 MiB dekodiert und 8.192 Pixel pro Seite, bis zu 16 Bilder pro Anfrage, und der gesamte JSON-Body unter 2 MiB. Nacktes Base64, SVG sowie eingebettetes Video oder Audio werden nicht akzeptiert. Eingebettete Bilder werden als Uploads in deinem Konto gespeichert, daher zeigt der input des Tasks eine popnow://-URI statt der Bytes.

Eine Datei hochladen

Hochladen braucht drei Aufrufe: ein Upload-Ticket holen, die Bytes per PUT senden, dann committen.

Ticket holen

FILE=reference.png
CONTENT_TYPE=image/png
BYTES=$(wc -c < "$FILE" | tr -d ' ')

TICKET=$(curl -s -X POST "https://api.popnow.ai/api/v1/common/upload-url" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contentType\": \"$CONTENT_TYPE\", \"bytes\": $BYTES}")
UPLOAD_URL=$(echo "$TICKET" | jq -r .data.uploadUrl)
FILE_ID=$(echo "$TICKET" | jq -r .data.fileId)

Die Antwort enthält fileId, uploadUrl, die genau so zu sendenden headers, expiresAt (etwa 20 Minuten später) und maxBytes. Einen Dateinamen gibt es nicht: Speicherpfade wählt immer der Server.

Bytes per PUT senden

curl -s -o /dev/null -w "%{http_code}\n" -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $CONTENT_TYPE" \
  -H "Content-Length: $BYTES" \
  --data-binary @"$FILE"

Sende jeden Header aus dem Ticket genau so, wie er dasteht – beide gehören zur Signatur – und keinen Authorization-Header. Im Browser lässt du Content-Length weg und schickst ein File oder Blob mit exakt der angegebenen Größe; der Browser setzt den Header selbst.

Committen

curl -s -X POST "https://api.popnow.ai/api/v1/files/$FILE_ID/commit" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Der Commit prüft Größe, Typ und Dateisignatur und liefert die URI, die du verwendest:

{
  "code": 200,
  "msg": "success",
  "data": {
    "fileId": "fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "status": "ready",
    "uri": "popnow://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "contentType": "image/png",
    "bytes": 402118,
    "width": 1024,
    "height": 1024,
    "expiresAt": "2026-10-17T09:12:00Z"
  },
  "request_id": "req_…"
}

Setz uri ins Feld des Modells, etwa "image_url": "popnow://f/fil_…". Eine popnow://-URI funktioniert nur mit Schlüsseln deines eigenen Kontos. Zweimal committen ist unbedenklich.

Upload-Grenzen

Typ	`contentType`	Größte Datei	Längste Dauer
Bild	`image/jpeg`, `image/png`, `image/webp`, `image/gif`	10 MiB	—
Video	`video/mp4`, `video/webm`	90 MiB	600 Sekunden
Audio	`audio/mpeg`, `audio/wav`	90 MiB	600 Sekunden
LoRA-Gewichte	`application/octet-stream` (eine `.safetensors`-Datei)	2 GiB	—

Ein Modell kann weniger akzeptieren; sein Schema sagt das pro Feld. Hochgeladene Dateien sind temporär – expiresAt in der Commit-Antwort sagt dir, wann die Datei gelöscht wird –, lade also kurz vor dem Erstellen des Tasks hoch. Was du wiederverwenden willst, speicherst du in deiner Asset-Bibliothek.

Antwortet ein Commit mit 40003, passen die gesendeten Bytes nicht zum Ticket (andere Größe, anderer Typ oder Inhalt). Hol ein neues Ticket und lade erneut hoch.

Ergebnisse herunterladen

Ein fertiger Task listet seine Dateien in output.assets, jede mit einer direkt nutzbaren url:

curl -L -o result.mp4 "$(curl -s "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY" | jq -r '.data.output.assets[0].url')"

Der Link ist signiert und gilt etwa 20 Minuten (expiresAt). Speichere ihn nicht; speichere die taskId und lies den Task für einen frischen Link erneut.
Schick beim Herunterladen keinen API-Schlüssel mit. Der Link selbst ist die Berechtigung – wer ihn hat, kann die Datei bis zum Ablauf herunterladen.
Um einen Link zu erzeugen, ohne den ganzen Task zu lesen, ruf POST /api/v1/common/download-url mit { "taskId": "…" } auf (optional mit dem key des Assets).

Die Dateien selbst bleiben bis zur Zeit in retention.outputsExpireAt des Tasks erhalten oder bis du den Task löschst. Was du darüber hinaus brauchst, kopierst du in deinen eigenen Speicher oder deine Asset-Bibliothek.

Medien

Auf dieser Seite