Die Erstellung der Lizenz und die Erstellung der Original-URL sind getrennt, sodass Wiederholungsversuche sicher sind und frische URLs nie erneut berechnet werden.
1. Lizenz erstellen
POST /api/v2/licenses
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932
{"media_id":123}Verwenden Sie einen eindeutigen Schlüssel aus 8 bis 160 druckbaren ASCII-Zeichen für den logischen Auswahlversuch und behalten Sie ihn beim erneuten Versuch bei. Eine neue Lizenz gibt 201 zurück; eine idempotente Wiederholung gibt 200 mit derselben Lizenz-ID zurück.
Cathopic prüft zuerst das Original. In einer einzigen Transaktion sperrt es das einzelne oder Team-Abonnement, prüft den Medienzugriff und vorhandene geteilte Berechtigungen, verbraucht höchstens einen Download und zeichnet die Berechtigung, die Historie und die Lizenz auf.
2. Original-URL anfordern
POST /api/v2/licenses/LICENSE_UUID/download-url
Authorization: Bearer ACCESS_TOKENDie URL läuft nach fünf Minuten ab. Fordern Sie für einen erneuten Download eine neue URL an; erstellen Sie keine weitere Lizenz. Cathopic leitet den Speicherpfad ab und akzeptiert niemals einen beliebigen Pfad.
Wichtige Fehler
subscription_required: kein aktiver bezahlter Zugriff.media_type_not_in_plan: Typ nicht enthalten.download_balance_exhausted: keine Downloads für den Tarif mit Kontingent mehr verfügbar.file_unavailable: Original fehlt; keine Berechnung.idempotency_key_conflict: Schlüssel wurde für eine andere Media-ID verwendet.
Bewahren Sie die X-Request-Id für den Support auf, aber protokollieren Sie niemals Tokens, Secrets oder signierte URLs. Gehen Sie nach 429 oder vorübergehenden 5xx-Antworten mit Jitter zurück.
