Referenz

Fehler und Limits

HTTP-Statuscodes, Fehlerformate, Credit-Limits und Timeout-Verhalten über alle Pedra-API-Endpunkte hinweg.

Fehlerantwortformat

Fehlgeschlagene Anfragen geben einen Nicht-200-HTTP-Status mit einem JSON-Body zurück, der ein error-Feld mit der Fehlerbeschreibung enthält.

JSON
{
  "error": "User not found"
}

Statuscodes

Die Pedra-API verwendet absichtlich eine kleine Menge von Statuscodes. Es gibt kein 401, kein 429, kein 413 — Authentifizierungs- und Quota-Fehler geben 404 bzw. 403 zurück, und es gibt heute keine serverseitigen Rate-Limits.

Status
Bedeutung
200
Erfolg. Bild-Endpunkte geben output zurück (Array oder einzelnes Objekt — siehe jeweiligen Endpunkt); der Video-Endpunkt gibt videoId und eine streamfähige videoUrl zurück.
400
Ungültige Anfrage. Bild-Endpunkte geben dies zurück, wenn imageUrl kein gültiges Bild liefert (Nicht-200-Antwort oder Bytes, die kein dekodierbares Bild sind). Wird außerdem von /api/create_video zurückgegeben bei fehlendem images-Array, fehlendem imageUrl in einem Bild, ungültigem effect-Wert oder effect: "transition" ohne secondImageUrl.
403
Nicht genügend Credits. Der Fehler-Body erklärt, wie viele Credits der Aufruf benötigte vs. wie viele übrig sind. Aufladen auf app.pedra.ai oder E-Mail an felix@pedra.ai.
404
{"error": "User not found"} — der API-Schlüssel passte zu keinem Konto. Das ist die Antwort für fehlende, ungültige oder widerrufene Schlüssel.
405
Methode nicht erlaubt. Alle Endpunkte akzeptieren nur POST.
500
Serverfehler. Zeigt meist die zugrundeliegende Verarbeitungsausnahme im error-Feld.

Häufige Fehler

User not found (404)

Der API-Schlüssel passte zu keinem Pedra-Konto. Stellen Sie sicher, dass der Schlüssel mit dem ausgegebenen übereinstimmt und sich im JSON-Body als apiKey befindet — nicht als Authorization-Header.

Insufficient credits (403)

Jeder Tarif beinhaltet ein monatliches Credit-Kontingent — siehe pedra.ai/pricing. Bild-Endpunkte kosten 1 Credit; jeder nicht-statische Video-Frame kostet 5. Wenn Sie aufgebraucht sind, erhalten Sie ein 403 mit der genauen Credit-Berechnung. Aufladen oder Tarif wechseln unter app.pedra.ai → Einstellungen → Abonnement und Credits.

Invalid effect 'X' at index N (400)

Der Video-Endpunkt validiert effect gegen die Menge [zoom-in, zoom-out, transition, static]. Die Fehlermeldung nennt den Bild-Index, der den Fehler verursacht.

imageUrl did not return a valid image (400)

Die imageUrl verwies nicht auf ein verwendbares Bild. Entweder antwortete die URL mit einem Nicht-200-Status (häufig eine 404-HTML-Fehlerseite unter einer .png-URL) oder die heruntergeladenen Bytes waren kein dekodierbares Bild. Öffnen Sie die URL in einem privaten Browserfenster, um zu bestätigen, dass sie die echte Bilddatei zurückgibt — keine Login-, Fehler- oder Platzhalterseite.

Image fetch failed (500)

Pedra konnte die imageUrl nicht innerhalb von 20 Sekunden herunterladen. Ursachen: Auth-geschützte URL, abgelaufene vorsignierte URL, langsame Quelle. Für vorsignierte S3/R2/Cloudinary-URLs senden Sie das Bild stattdessen als data:image-base64-URI — Pedra verwendet die Bytes direkt.

Rate-Limits

Es gibt heute keine pro-Sekunden- oder pro-Minuten-Rate-Limits in der Pedra-API. Der Durchsatz wird durch Ihre verbleibenden Credits und die zugrundeliegende Verarbeitungskapazität begrenzt. Wenn Sie hochvolumige Batches ausführen und einen garantierten Durchsatz benötigen, schreiben Sie an felix@pedra.ai.

Timeouts

  • Bild-Abruf: Pedra gibt nach 20 Sekunden auf, die imageUrl herunterzuladen.
  • Bild-Endpunkte (enhance, furnish, empty_room, renovation usw.): typische Antwortzeit 10–30 Sekunden.
  • Video-Endpunkt: synchron — blockiert während des Video-Renderings, das mehrere Minuten dauern kann. Setzen Sie das Timeout Ihres HTTP-Clients großzügig.

Sicheres erneutes Versuchen

Alle Endpunkte sind innerhalb einer Anfrage idempotent — die gleiche Anfrage erneut zu senden, erzeugt eine neue Generierung, niemals einen beschädigten Zustand. Fehlgeschlagene Anfragen (4xx/5xx) verbrauchen in den meisten Pfaden keine Credits; der Credit-Abzug erfolgt innerhalb der Meteor-Methode, sobald die Verarbeitung beginnt.

Brauchen Sie Hilfe?

Senden Sie eine E-Mail an felix@pedra.ai mit dem fehlgeschlagenen Request-Body und der Antwort. Wir antworten innerhalb eines Werktags. Siehe Preise für Credit- und Quoten-Optionen.