Riferimento

Errori e limiti

Codici di stato HTTP, formato errori, limiti di crediti e comportamento dei timeout su tutti gli endpoint dell'API Pedra.

Formato risposta di errore

Le richieste fallite restituiscono uno stato HTTP non-200 con un corpo JSON contenente un campo error che descrive cosa è andato storto.

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

Codici di stato

L'API Pedra usa un insieme volutamente piccolo di codici di stato. Niente 401, niente 429, niente 413 — gli errori di autenticazione e quota restituiscono 404 e 403 rispettivamente, e oggi non ci sono limiti di velocità lato server.

Stato
Significato
200
Successo. Gli endpoint immagini restituiscono output (array o singolo oggetto — vedi ogni endpoint); l'endpoint video restituisce videoId e una videoUrl pronta per lo streaming.
400
Richiesta non valida. Restituito da /api/create_video per array images mancante, imageUrl mancante in un'immagine, valore effect non valido o effect: "transition" senza secondImageUrl.
403
Crediti insufficienti. Il corpo dell'errore spiega quanti crediti richiedeva la chiamata vs. quanti ne restano. Ricarica su app.pedra.ai o scrivi a felix@pedra.ai.
404
{"error": "User not found"} — la chiave API non corrispondeva a nessun account. È la risposta per chiavi mancanti, non valide o revocate.
405
Metodo non consentito. Tutti gli endpoint accettano solo POST.
500
Errore del server. Mostra solitamente l'eccezione di elaborazione sottostante nel campo error. Per l'endpoint video, restituito anche al timeout interno di 10 minuti.

Errori comuni

User not found (404)

La chiave API non corrispondeva a nessun account Pedra. Verifica che la chiave corrisponda a quella emessa e che sia nel corpo JSON come apiKey — non come header Authorization.

Insufficient credits (403)

Ogni piano include un'allocazione mensile di crediti — vedi pedra.ai/pricing. Gli endpoint immagini costano 1 credito; ogni frame video non statico costa 5. Quando finisci, ricevi un 403 con il calcolo esatto dei crediti. Ricarica o cambia piano in app.pedra.ai → Impostazioni → Abbonamento e crediti.

Invalid effect 'X' at index N (400)

L'endpoint video convalida effect rispetto all'insieme [zoom-in, zoom-out, transition, static]. Il messaggio di errore indica l'indice dell'immagine problematica.

Video processing timeout after 10 minutes (500)

L'endpoint video si blocca fino a 10 minuti durante il rendering. Se il rendering supera questa finestra, l'endpoint restituisce 500. Il video potrebbe ancora completarsi in background — scrivi al supporto con il corpo della richiesta per recuperare l'URL finale.

Image fetch failed (500)

Pedra non è riuscita a scaricare imageUrl entro 20 secondi. Cause: URL con autenticazione, URL prefirmato scaduto, origine lenta. Per URL prefirmati S3/R2/Cloudinary, invia l'immagine come URI data base64 data:image — Pedra userà i byte direttamente.

Limiti di velocità

Oggi non ci sono limiti al secondo o al minuto sull'API Pedra. Il throughput è limitato dai crediti rimasti e dalla capacità di elaborazione sottostante. Se esegui batch ad alto volume e ti serve un floor di throughput garantito, scrivi a felix@pedra.ai.

Timeout

  • Download immagine: Pedra rinuncia dopo 20 secondi a scaricare imageUrl.
  • Endpoint immagini (enhance, furnish, empty_room, renovation, ecc.): risposta tipica 10–30 secondi.
  • Endpoint video: si blocca fino a 10 minuti. Imposta il timeout del client HTTP ad almeno 11 minuti.

Riprovare in sicurezza

Tutti gli endpoint sono idempotenti all'interno di una richiesta — riprovare con lo stesso corpo produce una nuova generazione, mai uno stato corrotto. Le richieste fallite (4xx/5xx) non consumano crediti nella maggior parte dei percorsi; la deduzione dei crediti avviene all'interno del metodo Meteor una volta avviata l'elaborazione.

Hai bisogno di aiuto?

Scrivi a felix@pedra.ai con il corpo della richiesta fallita e la risposta. Rispondiamo entro un giorno lavorativo. Vedi Prezzi per le opzioni di crediti e quote.