API Pro: limiti, codici di errore e buone pratiche

Limiti

Ogni chiave ne porta tre: render simultanei (2 per impostazione predefinita), richieste al minuto (60 per impostazione predefinita) e, se ne imposti uno, un limite giornaliero di crediti.

Superato un limite, la risposta è 429 con un'intestazione Retry-After in secondi. Una chiamata rifiutata non costa nulla. Il giorno usato per i limiti è il giorno UTC.

I video lunghi aggiungono due limiti propri: 30 shot per sequenza e 5 sequenze in corso per licenza (vedi Videos).

I personaggi ne hanno uno: 50 per licenza Pro, inclusi quelli creati nell'app, e un personaggio non utilizzato per un anno viene eliminato (vedi Characters). Luoghi, oggetti e animali hanno il loro, contato separatamente: 50 per licenza Pro (10 con una licenza personale, nell'app), eliminati dopo lo stesso anno di inutilizzo (vedi Luoghi, oggetti, animali, stili e outfit).

Il face swap ha due limiti propri: un passaggio di massimo 20 s per render, e il nostro server prepara due video alla volta. Superato ciò, la risposta è 429 server_busy: riprova dopo Retry-After (vedi Face swap). Tramite il MCP, un Face swap con transizione accetta un video intero di al massimo 60 s, e il server ne gestisce due alla volta: oltre, lo strumento chiede di riprovare tra qualche minuto.

La nostra scheda è condivisa con gli utenti dell'app. Quando è occupata, i tuoi render vengono inviati a GPU noleggiate, allo stesso prezzo e tramite la stessa API, con qualche decina di secondi in più all'avvio.

Codici di errore

Codice	error	Significato e cosa fare
400	prompt_required	Aggiungi un prompt.
400	forbidden_content	Il filtro contenuti ha rifiutato il prompt.
400	invalid_seed	seed deve essere un numero intero da 0 a 4294967295.
400	image_required, inpaint_images_required	La modalità richiede image_b64, e mask_b64 per inpaint.
401	key_required, invalid_key	Intestazione mancante o chiave sconosciuta.
402	insufficient_credits	Saldo insufficiente per questo render (viene indicato il cost). La risposta contiene buy_url, la pagina di acquisto crediti della tua licenza. Un render o un addestramento in corso riserva il suo prezzo fino al termine: engaged indica quanti crediti sono trattenuti in questo modo.
402	confirmation_required, payment_declined	Un acquisto con la tua carta salvata (POST /credits/purchase): la tua banca chiede la tua conferma o ha rifiutato il pagamento. Usa buy_url, il link di acquisto normale.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Un acquisto con la tua carta salvata: il tuo agente non è autorizzato ad acquistare (ricarica automatica della tua pagina account), nessuna carta è salvata, oppure l'acquisto supererebbe il tuo limite mensile. Usa buy_url.
409	topup_in_progress, purchase_in_progress	È in corso un altro pagamento con la tua carta salvata: attendi che finisca.
400	unknown_pack	Un acquisto con un pacchetto sconosciuto, o una quantità libera fuori dai limiti o non a scaglioni interi.
503	payment_unavailable	Il pagamento non ha potuto essere confermato: non sappiamo se l'addebito è avvenuto. Non riprovare subito; un addebito avvenuto viene accreditato.
403	key_disabled, key_revoked, key_expired	Chiave disattivata, revocata o scaduta: creane una nuova nell'app.
403	license_revoked, license_not_pro	Licenza revocata, o account non Pro.
403	missing_scope	Alla chiave manca il permesso richiesto, indicato in scope.
403	unknown_lora	Un personaggio che non appartiene all'account.
404	media_unavailable	Il file non è più disponibile: invia di nuovo.
404	unknown_lora	Su DELETE /loras/{name}, nessun file con quel nome sull'account. Nota il codice: lo stesso nome risponde 403 quando un render richiede un personaggio che non è tuo.
411	size_required	Un upload LoRA senza Content-Length. Il corpo è grezzo, quindi la dimensione deve essere annunciata.
413	file_too_large	Una LoRA superiore a 800 MB, o superiore a 90 MB in un singolo upload. Inviala in parti. Un 413 senza corpo JSON è un'altra cosa: la richiesta non ha mai raggiunto l'API, vedi la sezione upload.
413	part_too_large	Una parte è più grande del max_part_size annunciato dalla sessione.
404	unknown_upload_session	L'uploadId non esiste, o la sessione è stata abbandonata (sei ore) o annullata da una parte rifiutata.
503	upload_refused, part_refused	Lo storage non era raggiungibile durante l'upload: riprova.
507	storage_full	Spazio esaurito sullo storage del server (LoRA o sequenze in corso). Il team è stato avvisato: riprova più tardi.
415	invalid_safetensors	Il file caricato non è un safetensors.
415	incompatible_lora	La LoRA è per un'altra architettura, indicata in architecture. Le immagini accettano solo Krea 2, i video LTX 2.5 o 2.3. Nulla viene memorizzato e nessuna quota viene consumata.
413	lora_quota	Lo storage LoRA dell'account è pieno (20 file o 10 GB). La risposta indica quanto spazio rimane; elimina un file per liberarne.
413	image_too_large	Immagine sorgente o maschera superiori a 12 MB decodificati.
429	too_many_concurrent_renders, rate_limited, daily_cap	Un limite è stato raggiunto, vedi Retry-After.
429	daily_credit_cap	Il limite giornaliero di crediti della chiave è stato raggiunto (cap, spent, cost).
502	submission_failed, status_failed	Un incidente lato render: riprova tra qualche secondo.
503	license_check_failed	L'account non può essere verificato in questo momento: riprova tra un minuto.
400	invalid_extend_frames	Un'estensione il cui extend_frames non è 9, 17, 25, 33, 41 o 49, o un extend_video che non ha esattamente quel numero di frame.
400	extension_with_transition	Un'estensione non può essere anche una transizione, tranne con consistency enhanced: rimuovi end_image, o richiedi la coerenza rafforzata.
400	extension_too_short	La length di un'estensione conta solo i nuovi frame e deve essere almeno 9.
404	clip_unavailable	Il clip da estendere non è più disponibile: estendilo prima, o invia la sua fine in extend_video. Come 502, la lettura è fallita: riprova.
404	unknown_clip	Il clip da estendere appartiene a un'altra licenza.
404	unknown_sequence	La sequenza non esiste, appartiene a un'altra licenza o è scaduta.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips senza job_id, o l'esportazione di una sequenza senza shot.
409	not_exported_yet	GET /sequences/{id}/file prima dell'esportazione: chiama prima POST /sequences/{id}/export.
404	unknown_export	Esportazione della cartella di progetto: render sconosciuto, di un'altra licenza o inviato più di 24 h fa; ZIP cancellato (45 min dopo il primo download, al massimo 2 h).
409	export_in_progress	Un'esportazione di cartella di progetto alla volta per licenza.
413	export_too_large	Cartella di progetto oltre 2 GB: esporta le inquadrature una per una.
400	unknown_reference	Esportazione della cartella di progetto: una voce di exclude_references non designa alcun riferimento dell'esportazione (né id, né nome, né @menzione).
400	invalid_export_options	Esportazione della cartella di progetto: un'opzione che non è un booleano, un exclude_references che non è una lista di testi, o include_film senza include_media.
500	export_failed	L'esportazione non è riuscita (motivo in detail): non viene addebitato nulla, riprova.
422	resolution_mismatch, unreadable_clip	Un render archiviato manualmente (POST /sequences/{id}/clips) a una risoluzione diversa da quella della sequenza, o illeggibile.
409	missing_shot	Uno shot non è ancora terminato, o non è più disponibile (il job_id lo identifica): aspetta che finisca, poi esporta di nuovo.
409	sequence_exported	La sequenza è già assemblata.
409	audio_mismatch	Uno shot con audio in una sequenza silenziosa, o viceversa.
413	extend_video_too_large	La fine del clip inviata supera 8 MB.
413	too_many_shots	Massimo 30 shot per sequenza.
422	unreadable_tail	La fine del clip, inviata o riletta, non è un video leggibile.
422	assembly_failed	Gli shot hanno risoluzioni diverse, o l'audio è presente solo su alcuni di essi.
503	ultra_unavailable	La modalità Ultra è momentaneamente chiusa: riprova più tardi, o genera senza quality.
503	ultra_4k_unavailable	Una dimensione 4K richiesta in Ultra: il 4K non è più offerto, il video arriva fino a 1080p (1920 x 1088).
400	ultra_incompatible	Una transizione (end_image) richiesta in Ultra.
400	extension_4k	La continuazione di un vecchio clip 4K: il 4K non è più offerto, un clip 4K non si può più prolungare (ultra_4k_unavailable con quality: "max"). Prolunga un clip di al massimo 1080p.
400	resolution_above_quality	Una dimensione superiore a 1080p (1920 x 1088) senza quality: "max": 1080p è il massimo in ogni modalità.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Fotogrammi chiave fuori dai limiti: più di 4, un'immagine o una forza non valida; un momento fuori dal clip, o due fotogrammi chiave a meno di 0,5 s di distanza; una modalità diversa da Qualità (Ultra, Multi-Ref), o un'estensione senza consistency enhanced.
400	invalid_consistency, consistency_mode	consistency diverso da standard o enhanced; coerenza rafforzata richiesta in Ultra o in Multi-Ref.
400	consistency_explicit	Un prompt che la coerenza rafforzata non rende ancora, oltre i 20 s (15 s con un end_image), in un'estensione o in una sequenza (un singolo shot più breve viene reso in coerenza standard): accorcialo, o usa standard.
403	consistency_licensed_only	La coerenza rafforzata è riservata alle licenze.
503	consistency_unavailable	La coerenza rafforzata è momentaneamente chiusa: riprova più tardi, o genera in standard.
409	consistency_mismatch	Uno shot la cui consistency differisce da quella della sequenza.
422	encoding_mismatch	Un render archiviato manualmente (POST /sequences/{id}/clips) la cui consistency differisce dagli shot già archiviati.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	Un frame rate (fps) che la modalità non supporta (detail elenca quelli disponibili); coerenza rafforzata sopra i 30 fps con durata automatica (imposta duration_auto su false e fornisci length); un'estensione a un frame rate diverso dal clip precedente.
409	sequence_fps_mismatch	Uno shot il cui frame rate (fps) differisce da quello della sequenza.
503	keyframes_unavailable	I fotogrammi chiave sono momentaneamente chiusi: genera senza keyframes.
429	too_many_sequences	Massimo 5 sequenze in corso per licenza: esportane una, o aspetta che una scada.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Un campo personaggio fuori dai limiti (vedi Characters).
400	image_too_small	Una foto con il lato lungo inferiore a 1024 px.
415	unsupported_image_format, unreadable_image	Una foto o un'immagine di ambientazione che non è un JPEG, PNG o WebP leggibile.
404	unknown_character	Il character_id non è sulla tua licenza, o è stato eliminato (un anno di inutilizzo, o eliminato nell'app).
409	character_limit	Il limite di personaggi (max) è stato raggiunto: eliminane uno.
409	character_busy	Le sue viste sono in fase di creazione: aspetta che lo status non sia più pending. Su POST /characters: la stessa creazione è in corso di registrazione, inviala di nuovo qualche secondo dopo.
409	photo_view, empty_character, single_image_sheet	La vista proveniente dalla foto originale non può essere rifatta; o il personaggio non ha nessuna vista leggibile (se è lo storage a rifiutare la lettura: 503 storage_unavailable, riprova); oppure una sheet importata come immagine unica (mantenuta così com'è): le sue viste non si rifanno e non veste una nuova sheet (invia la vista 4 o 1).
409	app_character	Un'instruction o una vista caricata su un personaggio o una character sheet fatti nell'app: riservato ai personaggi e alle character sheet creati tramite API.
400	instruction_too_long	Un'instruction più lunga di 200 caratteri.
400	outfit_or_views_required	Una character sheet aggiunta senza outfit né views: indica un outfit da generare, o delle viste.
400	views_required	Una character sheet aggiunta con generate: false: indica almeno una vista.
409	source_sheet_empty	Una character sheet aggiunta senza vista a figura intera né busto, a un personaggio che non ha nessuno dei due da cui partire: inviane uno in views.
404	unknown_sheet	Solo una character sheet aggiunta tramite API (sheet_origin api) si elimina con DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	Il subject_id non è sulla tua licenza, o è stato eliminato dopo un anno di inutilizzo.
409	subject_limit	Il limite di soggetti (max) è stato raggiunto: luoghi, oggetti, animali, stili e outfit contano insieme; eliminane uno.
409	empty_subject	Un soggetto senza immagini leggibili.
400	invalid_type, description_too_long, invalid_images	Un campo soggetto fuori dai limiti (vedi Luoghi, oggetti, animali, stili e outfit).
400	invalid_image	Un'immagine soggetto che non è un JPEG, PNG o WebP leggibile di almeno 512 px sul lato lungo (index indica quale).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Generare un soggetto: né description, né prompt, né immagine di partenza; una chiave di vista che il tipo non ha (detail dà l'elenco); count fuori da 1 a 6, o più di 6 immagini, partenza compresa; un prompt di oltre 2000 caratteri; instructions vuote, troppo lunghe o per più viste.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	Una serie è già in corso su questo soggetto; un soggetto creato da immagini (aggiungine con /images); una vista già fatta (rifalla); una partenza da rifare mentre ne partono delle viste; una partenza non riuscita da rifare prima; una partenza importata, che non si rifà.
404 / 503	unknown_view, generation_unavailable	Una vista mai richiesta (aggiungila); la generazione di soggetti non è disponibile sul server per il momento: riprova più tardi.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref fuori dai limiti: da 1 a 4 personaggi (12 in Ultra), nessuna estensione o transizione, i formati e le durate di Multi-Ref Video.
400	duplicate_name, invalid_strength, unknown_mention	Due personaggi con lo stesso nome; strength fuori dall'intervallo 0-2; un @Nome nel prompt senza personaggio corrispondente (mentions li elenca).
400	voice_requires_audio, voice_slot	Una voce del personaggio (voice_b64) senza audio ("audio": true); o su un personaggio diverso da characters[0] e characters[1] (il motore supporta 2 voci). index indica quale.
400	invalid_voice_choice	voice diverso da character o original in un Face swap, oppure characters[].voice diverso da character o generated in Multi-Ref Video.
413	audio_too_large	Una voce del personaggio superiore a 4 MB, o superiore a 2 MB in un Face swap. Solo i primi 5 secondi vengono utilizzati (20 in un Face swap): invia un breve estratto.
415	unsupported_audio_format	Una voce del personaggio che non è un file audio leggibile (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Più di 4 personaggi, oggetti e animali in totale, fuori dall'Ultra; un soggetto nel campo sbagliato (un'ambientazione in subjects, un oggetto come location, uno stile fuori da styles, un outfit fuori da outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Crea un'immagine: count 1 o 2, view da 1 a 5 e presente nella sheet, lora_pass da 0,3 a 0,9, l'image di un soggetto tra le sue immagini, larghezza e altezza da 256 a 2048.
400	character_not_ready	Crea un'immagine: la vista scelta di un personaggio non ha ancora un'immagine.
503	multiref_image_disabled	La creazione di un'immagine non è ancora aperta su questo server.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Stili, outfit o movimento fuori dal Multi-Ref in Ultra; più di 30 immagini in Ultra; un worn_by che non nomina nessun personaggio.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion senza motion_id né video_b64; un mode diverso da camera o choreography; un video illeggibile, o fuori da 4 a 30 s (input_video_out_of_limits); un motion_id mai caricato (nessun PUT).
404 / 409	unknown_motion, motion_already_used	Un motion_id sconosciuto, già usato o più vecchio di 2 ore: carica di nuovo il video.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	Un video di movimento oltre 20 MB (20 MB una volta riportato a 480p); il movimento non è ancora aperto (ultra.motion_per_second vale null); un mode non ancora aperto.
409	extension_link_expired	Un extend_job_id che la tua licenza non conosce, o un'inquadratura Ultra di più di 24 ore: carica il suo originale (POST /extensions) e passa extend_upload_id.
400	extension_real_face	Il video da prolungare in Ultra non è stato renderizzato in modalità Ultra (il render di un'altra modalità, per esempio) e mostra un volto realistico: non viene addebitato nulla. Prolungalo in modalità Qualità, oppure rifai l'inquadratura in Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Estensione Ultra fuori dai limiti: extend_upload_id o backward senza quality: "max" (o da un clip che non è Ultra); un'immagine iniziale, riferimenti, movimento o coerenza rafforzata insieme; una direzione diversa da forward o backward; backward in una sequenza; extend_video in Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	Un video caricato oltre il 1080p; un MP4 illeggibile, o fuori da 4 a 30 s (input_video_out_of_limits); un file mai caricato (nessun PUT).
400	input_video_out_of_limits	Un video inviato alla modalità Ultra (movimento, video da prolungare) fuori dai suoi limiti, controllati prima del rendering, nulla addebitato: limit dice quale (duration: da 4 a 30 s; total_duration: 30 s con i suoni di riferimento; count: 10; size: 200 MB; format: MP4 o MOV; fps: da 24 a 60; pixels: larghezza × altezza da 409 600 a 8 295 044; aspect_ratio: da 0,4 a 2,5), con value, min e max.
404 / 409	unknown_extension_upload, extension_upload_used	Un extend_upload_id sconosciuto, più vecchio di 2 ore o già usato: carica di nuovo il file.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	Un file oltre 60 MB; l'estensione Ultra non è ancora aperta (ultra.extend_per_second vale null); all'indietro non è ancora aperta.
413	references_too_large	Le viste preparate superano il budget del render: usa meno personaggi, o un formato più piccolo.
400	video_required, character_required	Un Face swap senza video_b64, o senza character_id.
413	video_too_large	Un video Face swap superiore a 20 MB: taglialo o comprimilo prima, o usa lo strumento MCP tendre_face_swap, che accetta fino a 95 MB.
415	unreadable_video	Il video Face swap non è un MP4, MOV, WebM o MKV leggibile.
400	invalid_start, invalid_duration, passage_too_short	Un passaggio Face swap fuori dai limiti: start sotto 0 o oltre la fine del video; duration fuori dall'intervallo 0,5-20 s; un passaggio più corto di mezzo secondo.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Un campo Face swap fuori dai limiti: zone diverso da tight, normal o wide; part diverso da full o head; likeness fuori dall'intervallo 0,5-2; scene oltre 400 caratteri; description oltre 360; name oltre 60.
413	face_swap_too_large	Il passaggio è ancora troppo pesante una volta preparato: specifica una duration più breve.
429	server_busy	Il nostro server sta già preparando due video Face swap: riprova dopo Retry-After (20 s). Il link di upload MCP risponde con lo stesso codice come 503 quando troppi file sono in attesa: riprova tra qualche minuto.
503	face_swap_unavailable, face_swap_price_missing	Il Face swap è chiuso, o non ha un prezzo, al momento: riprova più tardi.
503	creation_unavailable, multiref_unavailable, storage_unavailable	Il servizio è temporaneamente non disponibile: riprova più tardi.
500	internal_error	Un incidente imprevisto lato server: riprova, e segnalacelo se si ripete.

Ultra fatturato al secondo (Ultra):

Codice	error	Significato e cosa fare
400	resolution_outside_ultra	Oltre il 1080p: 480p, 720p o 1080p.
400	engine_refused	Il motore rifiuta il testo o un'immagine: il motivo è in detail e il codice in code. Non viene addebitato nulla: riformula.
502	engine_unavailable	Il motore non risponde: riprova tra qualche minuto. Non viene addebitato nulla.
409	render_in_progress	Annullamento di un rendering già in calcolo: non si ferma più, viene consegnato e fatturato.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref in Ultra: un'immagine di riferimento è illeggibile o troppo pesante (20 MB al massimo in tutto), oppure un'opzione non è supportata.
403	multiref_ultra_unavailable	Il Multi-Ref in Ultra fatturato al secondo non è ancora aperto per questo account.

I nomi degli errori sono le stringhe esatte restituite dall'API. Confrontali su di esse piuttosto che sul messaggio, che potrebbe essere riformulato.

Una risposta non è un errore: un render Multi-Ref o un Face swap con un personaggio che ha una sola vista viene elaborato, con un avviso limited_likeness in warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). La somiglianza è limitata: crea le sette viste del personaggio per una somiglianza fedele.

Anche un render Multi-Ref in Ultra con da 9 a 12 personaggi viene elaborato, con un avviso many_characters: alcuni possono mancare o mescolarsi (se ne consigliano 8).

Buone pratiche

• Fai polling ogni 3 secondi, non più frequentemente. La coda è condivisa e martellare non aiuta nessuno.
• Scarica non appena lo stato è completed. Il file non è archiviato.
• Scrivi i prompt in inglese, e per i video descrivi il movimento piuttosto che l'immagine statica.
• Una chiave per utilizzo, e un limite giornaliero di crediti su ogni chiave che vive su un server. Una chiave trapelata con un limite ti costa un giorno, non l'intero saldo.
• Tratta un 429 come normale, non come un errore: aspetta Retry-After e continua.
• Una connessione interrotta prima della risposta non costa nulla. Se un invio di immagine o video resta senza risposta (timeout di un proxy, errore 524, programma arrestato), il rendering non viene avviato, oppure viene annullato subito, e non viene addebitato nulla: basta inviare di nuovo la richiesta. Per un lotto di immagini (count), anche i rendering già creati vengono annullati. La creazione di un personaggio, invece, continua: inviare di nuovo la stessa richiesta restituisce lo stesso personaggio, senza addebitare nulla due volte (vedi Characters).

I prompt vengono registrati da parte nostra, come avviene per l'app, per motivi di sicurezza.