Pro API: limieten, foutcodes en best practices

Limieten

Elke sleutel heeft er drie: gelijktijdige renders (standaard 2), aanvragen per minuut (standaard 60) en, als je er een instelt, een dagelijks creditlimiet.

Als een limiet is bereikt, is het antwoord 429 met een Retry-After-header in seconden. Een geweigerde aanroep kost niets. De dag die voor de limieten wordt gebruikt, is de UTC-dag.

Lange video's voegen twee eigen limieten toe: 30 shots per reeks en 5 reeksen tegelijk per licentie (zie Video's).

Personages hebben er één: 50 per Pro-licentie, inclusief de in de app gemaakte personages, en een personage dat één jaar niet wordt gebruikt, wordt verwijderd (zie Personages). Locaties, objecten en dieren hebben hun eigen limiet, apart geteld: 50 per Pro-licentie (10 bij een persoonlijke licentie, in de app), verwijderd na datzelfde jaar ongebruikt (zie Locaties, objecten, dieren, stijlen en outfits).

Face swap heeft twee eigen limieten: een fragment van maximaal 20 s per render, en onze server bereidt twee video's tegelijk voor. Daarna is het antwoord 429 server_busy: wacht tot na Retry-After (zie Face swap). Via de MCP neemt een Face swap met overgang een hele video van maximaal 60 s, en de server verwerkt er twee tegelijk: daarboven vraagt de tool het over een paar minuten opnieuw te proberen.

Onze eigen kaart wordt gedeeld met de gebruikers van de app. Als die bezet is, gaan je renders naar gehuurde GPU's, tegen dezelfde prijs en via dezelfde API, met een paar tientallen seconden extra bij het opstarten.

Foutcodes

Code	error	Wat het betekent en wat je moet doen
400	prompt_required	Voeg een prompt toe.
400	forbidden_content	Het inhoudsfilter heeft de prompt geweigerd.
400	invalid_seed	seed moet een geheel getal zijn van 0 tot 4294967295.
400	image_required, inpaint_images_required	De modus vereist image_b64, en mask_b64 voor inpaint.
401	key_required, invalid_key	Header ontbreekt of sleutel is onbekend.
402	insufficient_credits	Onvoldoende saldo voor deze render (cost wordt vermeld). Het antwoord bevat buy_url, de pagina om credits te kopen voor je licentie. Een render of training die bezig is, reserveert de prijs tot deze klaar is: engaged geeft aan hoeveel credits op die manier zijn gereserveerd.
402	confirmation_required, payment_declined	Een aankoop met je opgeslagen kaart (POST /credits/purchase): je bank vraagt je bevestiging, of heeft de betaling geweigerd. Gebruik buy_url, de gewone aankooplink.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Een aankoop met je opgeslagen kaart: je agent mag niet kopen (automatisch opwaarderen op je accountpagina), er is geen kaart opgeslagen, of de aankoop zou je maandelijkse limiet overschrijden. Gebruik buy_url.
409	topup_in_progress, purchase_in_progress	Er loopt al een andere betaling met je opgeslagen kaart: wacht tot die klaar is.
400	unknown_pack	Een aankoop met een onbekend pakket, of een vrij aantal buiten de grenzen of niet in hele stappen.
503	payment_unavailable	De betaling kon niet worden bevestigd: we weten niet of de afschrijving is gelukt. Probeer het niet meteen opnieuw; een gelukte afschrijving wordt bijgeschreven.
403	key_disabled, key_revoked, key_expired	Sleutel uitgeschakeld, ingetrokken of verlopen: maak een nieuwe aan in de app.
403	license_revoked, license_not_pro	Licentie ingetrokken, of een account dat geen Pro is.
403	missing_scope	De sleutel mist de gevraagde toestemming, vermeld in scope.
403	unknown_lora	Een personage dat niet tot het account behoort.
404	media_unavailable	Het bestand is verdwenen: dien opnieuw in.
404	unknown_lora	Bij DELETE /loras/{name} bestaat er geen bestand met die naam op het account. Let op de code: dezelfde naam geeft 403 terug als een render een personage opvraagt dat niet van jou is.
411	size_required	Een LoRA-upload zonder Content-Length. De body is onbewerkt, dus de grootte moet vooraf worden aangekondigd.
413	file_too_large	Een LoRA van meer dan 800 MB, of meer dan 90 MB in één upload. Verstuur het in delen. Een kale 413 zonder JSON-body is iets anders: het verzoek heeft de API nooit bereikt, zie de uploadsectie.
413	part_too_large	Één deel is groter dan de max_part_size die de sessie heeft aangekondigd.
404	unknown_upload_session	De uploadId bestaat niet, of de sessie is verlaten (zes uur) of geannuleerd door een geweigerd deel.
503	upload_refused, part_refused	De opslag was niet bereikbaar tijdens de upload: probeer opnieuw.
507	storage_full	Er is geen ruimte meer op de serveropslag (LoRA's of reeksen in uitvoering). Het team wordt gewaarschuwd: probeer het later opnieuw.
415	invalid_safetensors	Het geüploade bestand is geen safetensors.
415	incompatible_lora	De LoRA is voor een andere architectuur, vermeld in architecture. Afbeeldingen gebruiken alleen Krea 2, video's LTX 2.5 of 2.3. Er wordt niets opgeslagen en er wordt geen quota gebruikt.
413	lora_quota	De LoRA-opslag van het account is vol (20 bestanden of 10 GB). Het antwoord geeft aan wat er nog over is; verwijder een bestand om ruimte te maken.
413	image_too_large	Bronafbeelding of masker groter dan 12 MB gedecodeerd.
429	too_many_concurrent_renders, rate_limited, daily_cap	Een limiet is bereikt, zie Retry-After.
429	daily_credit_cap	Het dagelijkse creditlimiet van de sleutel is bereikt (cap, spent, cost).
502	submission_failed, status_failed	Een storing aan de renderkant: probeer het over een paar seconden opnieuw.
503	license_check_failed	Het account kan momenteel niet worden gecontroleerd: probeer het over een minuut opnieuw.
400	invalid_extend_frames	Een verlenging waarvan extend_frames niet 9, 17, 25, 33, 41 of 49 is, of een extend_video dat niet precies dat aantal frames heeft.
400	extension_with_transition	Een verlenging kan geen overgang zijn, behalve bij consistency enhanced: verwijder end_image, of vraag versterkte samenhang aan.
400	extension_too_short	De length van een verlenging telt alleen de nieuwe frames en moet minimaal 9 zijn.
404	clip_unavailable	Het te verlengen clip is niet meer beschikbaar: verleng het eerder, of stuur het einde in via extend_video. Als 502, is het lezen mislukt: probeer opnieuw.
404	unknown_clip	Het te verlengen clip behoort tot een andere licentie.
404	unknown_sequence	De reeks bestaat niet, behoort tot een andere licentie of is verlopen.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips zonder job_id, of de export van een reeks die geen shot heeft.
409	not_exported_yet	GET /sequences/{id}/file vóór de export: roep eerst POST /sequences/{id}/export aan.
404	unknown_export	Export van de projectmap: onbekende render, van een andere licentie of meer dan 24 u geleden ingediend; ZIP gewist (45 min na de eerste download, hoogstens 2 u).
409	export_in_progress	Eén export van een projectmap tegelijk per licentie.
413	export_too_large	Projectmap groter dan 2 GB: exporteer de shots een voor een.
400	unknown_reference	Export van de projectmap: een item van exclude_references wijst geen enkele referentie van de export aan (geen id, naam of @vermelding).
400	invalid_export_options	Export van de projectmap: een optie die geen boolean is, een exclude_references dat geen lijst van teksten is, of include_film zonder include_media.
500	export_failed	De export is mislukt (reden in detail): er wordt niets afgeschreven, probeer opnieuw.
422	resolution_mismatch, unreadable_clip	Een handmatig ingediende render (POST /sequences/{id}/clips) met een andere resolutie dan de reeks, of onleesbaar.
409	missing_shot	Een shot is nog niet klaar of niet meer beschikbaar (job_id noemt het): wacht tot het klaar is en exporteer opnieuw.
409	sequence_exported	De reeks is al samengesteld.
409	audio_mismatch	Een shot met geluid in een stille reeks, of andersom.
413	extend_video_too_large	Het clipuiteinde dat je hebt verstuurd is groter dan 8 MB.
413	too_many_shots	Maximaal 30 shots per reeks.
422	unreadable_tail	Het clipuiteinde, verstuurd of teruggelezen, is geen leesbare video.
422	assembly_failed	De shots hebben verschillende resoluties, of slechts een deel ervan heeft geluid.
503	ultra_unavailable	Ultra-modus is momenteel gesloten: probeer het later opnieuw, of render zonder quality.
503	ultra_4k_unavailable	Een 4K-formaat gevraagd in Ultra: 4K wordt niet meer aangeboden, video gaat tot 1080p (1920 x 1088).
400	ultra_incompatible	Een overgang (end_image) aangevraagd in Ultra.
400	extension_4k	De voortzetting van een eerdere 4K-clip: 4K wordt niet meer aangeboden, een 4K-clip kan niet worden verlengd (ultra_4k_unavailable met quality: "max"). Verleng een clip van maximaal 1080p.
400	resolution_above_quality	Een formaat boven 1080p (1920 x 1088) zonder quality: "max": 1080p is het maximum in elke modus.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Keyframes buiten de grenzen: meer dan 4, een ongeldige afbeelding of sterkte; een moment buiten het clip, of twee keyframes minder dan 0,5 s uit elkaar; een andere modus dan Kwaliteit (Ultra, Multi-Ref), of een verlenging zonder consistency enhanced.
400	invalid_consistency, consistency_mode	consistency anders dan standard of enhanced; versterkte samenhang aangevraagd in Ultra of in Multi-Ref.
400	consistency_explicit	Een prompt die versterkte samenhang nog niet rendert, langer dan 20 s (15 s met een end_image), in een verlenging of in een reeks (een enkel korter shot rendert in standaard samenhang): maak het korter, of gebruik standard.
403	consistency_licensed_only	Versterkte samenhang is voorbehouden aan licentiehouders.
503	consistency_unavailable	Versterkte samenhang is momenteel gesloten: probeer het later opnieuw, of render in standard.
409	consistency_mismatch	Een shot waarvan de consistency afwijkt van die van de reeks.
422	encoding_mismatch	Een handmatig ingediende render (POST /sequences/{id}/clips) waarvan de consistency afwijkt van de al ingediende shots.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	Een framerate (fps) die de modus niet heeft (detail geeft de beschikbare op); versterkte samenhang boven 30 fps met automatische duur (stel duration_auto in op false en geef length op); een verlenging met een andere framerate dan het vorige clip.
409	sequence_fps_mismatch	Een shot waarvan de framerate (fps) afwijkt van die van de reeks.
503	keyframes_unavailable	Keyframes zijn momenteel gesloten: render zonder keyframes.
429	too_many_sequences	Maximaal 5 reeksen tegelijk per licentie: exporteer er een, of wacht tot er een verloopt.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Een personageveld buiten de grenzen (zie Personages).
400	image_too_small	Een foto kleiner dan 1024 px op de lange zijde.
415	unsupported_image_format, unreadable_image	Een foto of locatieafbeelding die geen leesbare JPEG, PNG of WebP is.
404	unknown_character	De character_id staat niet op je licentie, of is verwijderd (één jaar ongebruikt, of verwijderd in de app).
409	character_limit	Het personagelimiet (max) is bereikt: verwijder er een.
409	character_busy	De weergaven worden aangemaakt: wacht tot status niet meer pending is. Bij POST /characters: dezelfde aanmaak wordt nog opgeslagen, stuur hem een paar seconden later opnieuw.
409	photo_view, empty_character, single_image_sheet	De weergave die afkomstig is van de originele foto kan niet opnieuw worden gemaakt; of het personage heeft geen leesbare weergave (als de opslag het lezen weigert: 503 storage_unavailable, probeer het opnieuw); of een sheet die als één afbeelding is geïmporteerd (ongewijzigd bewaard): de weergaven worden niet opnieuw gemaakt en hij kleedt geen nieuwe sheet aan (stuur weergave 4 of 1).
409	app_character	Een instruction of een geüploade weergave op een personage of een sheet uit de app: voorbehouden aan personages en sheets die via de API zijn aangemaakt.
400	instruction_too_long	Een instruction langer dan 200 tekens.
400	outfit_or_views_required	Een sheet toegevoegd zonder outfit en zonder views: geef een outfit om te genereren, of weergaven.
400	views_required	Een sheet toegevoegd met generate: false: geef minstens één weergave.
409	source_sheet_empty	Een sheet toegevoegd zonder volledige weergave en zonder buste, aan een personage dat geen van beide heeft om van uit te gaan: stuur er een in views.
404	unknown_sheet	Alleen een sheet die via de API is toegevoegd (sheet_origin api), verwijder je met DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	De subject_id staat niet op je licentie, of is verwijderd na één jaar ongebruikt.
409	subject_limit	Het limiet voor onderwerpen (max) is bereikt: locaties, objecten, dieren, stijlen en outfits tellen samen; verwijder er een.
409	empty_subject	Een onderwerp zonder leesbare afbeelding.
400	invalid_type, description_too_long, invalid_images	Een onderwerpveld buiten de grenzen (zie Locaties, objecten, dieren, stijlen en outfits).
400	invalid_image	Een onderwerpafbeelding die geen leesbare JPEG, PNG of WebP is van minimaal 512 px op de lange zijde (index geeft aan welke).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Een onderwerp genereren: geen description, geen prompt en geen startafbeelding; een weergavesleutel die het type niet heeft (detail geeft de lijst); count buiten 1 tot 6, of meer dan 6 afbeeldingen, start inbegrepen; een prompt van meer dan 2000 tekens; instructions leeg, te lang of voor meerdere weergaven.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	Er loopt al een reeks op dit onderwerp; een onderwerp gemaakt van afbeeldingen (voeg afbeeldingen toe via /images); een weergave die al gemaakt is (maak hem opnieuw); een start om opnieuw te maken terwijl er weergaven van uitgaan; een mislukte start die eerst opnieuw moet; een geïmporteerde start, die niet opnieuw kan.
404 / 503	unknown_view, generation_unavailable	Een weergave die nooit gevraagd is (voeg hem toe); het genereren van onderwerpen is op dit moment niet beschikbaar op de server: probeer het later opnieuw.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref buiten de grenzen: 1 tot 4 personages (12 in Ultra), geen verlenging of overgang, de formaten en lengtes van Multi-Ref Video.
400	duplicate_name, invalid_strength, unknown_mention	Twee personages met dezelfde naam; strength buiten 0 tot 2; een @Naam in de prompt zonder bijbehorend personage (mentions geeft ze op).
400	voice_requires_audio, voice_slot	Een personagestem (voice_b64) zonder geluid ("audio": true); of op een ander personage dan characters[0] en characters[1] (de engine ondersteunt 2 stemmen). index geeft aan welke.
400	invalid_voice_choice	voice anders dan character of original bij een Face swap, of characters[].voice anders dan character of generated bij Multi-Ref Video.
413	audio_too_large	Een personagestem groter dan 4 MB, of groter dan 2 MB bij een Face swap. Alleen de eerste 5 seconden worden gebruikt (20 bij een Face swap): stuur een kort fragment.
415	unsupported_audio_format	Een personagestem die geen leesbaar audiobestand is (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Meer dan 4 personages, objecten en dieren samen, buiten Ultra; een onderwerp in het verkeerde veld (een locatie in subjects, een object als location, een stijl buiten styles, een outfit buiten outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Afbeelding maken: count 1 of 2, view 1 tot 5 en aanwezig in de sheet, lora_pass 0,3 tot 0,9, de image van een onderwerp verwijst naar een van zijn afbeeldingen, breedte en hoogte van 256 tot 2048.
400	character_not_ready	Afbeelding maken: de gekozen weergave van een personage heeft nog geen afbeelding.
503	multiref_image_disabled	Afbeelding maken is nog niet open op deze server.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Stijlen, outfits of beweging buiten Multi-Ref in Ultra; meer dan 30 afbeeldingen in Ultra; een worn_by die geen personage noemt.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion zonder motion_id en zonder video_b64; een andere mode dan camera of choreography; een onleesbare video, of een buiten 4 tot 30 s (input_video_out_of_limits); een motion_id die nooit is geüpload (geen PUT).
404 / 409	unknown_motion, motion_already_used	Een motion_id die onbekend is, al gebruikt of ouder dan 2 uur: upload de video opnieuw.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	Een bewegingsvideo van meer dan 20 MB (20 MB na terugbrengen naar 480p); de beweging is nog niet open (ultra.motion_per_second is null); een mode die nog niet open is.
409	extension_link_expired	Een extend_job_id die je licentie niet kent, of een Ultra-shot ouder dan 24 uur: upload het origineel (POST /extensions) en geef extend_upload_id door.
400	extension_real_face	De video die je in Ultra wilt verlengen is niet in de Ultra-modus gerenderd (de render van een andere modus, bijvoorbeeld) en toont een realistisch gezicht: er wordt niets afgeschreven. Verleng hem in Kwaliteit-modus, of maak de shot opnieuw in Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Ultra-verlenging buiten de grenzen: extend_upload_id of backward zonder quality: "max" (of vanaf een clip die niet Ultra is); een startafbeelding, referenties, beweging of versterkte consistentie erbij; een andere richting dan forward of backward; backward in een reeks; extend_video in Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	Een geüploade video boven 1080p; een onleesbare MP4, of een buiten 4 tot 30 s (input_video_out_of_limits); een bestand dat nooit is geüpload (geen PUT).
400	input_video_out_of_limits	Een video die naar de Ultra-modus gaat (beweging, te verlengen video) buiten de grenzen, gecontroleerd vóór de render, niets afgeschreven: limit zegt welke (duration: 4 tot 30 s; total_duration: 30 s met de referentiegeluiden; count: 10; size: 200 MB; format: MP4 of MOV; fps: 24 tot 60; pixels: breedte × hoogte van 409.600 tot 8.295.044; aspect_ratio: 0,4 tot 2,5), met value, min en max.
404 / 409	unknown_extension_upload, extension_upload_used	Een extend_upload_id die onbekend is, ouder dan 2 uur of al gebruikt: upload het bestand opnieuw.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	Een bestand van meer dan 60 MB; de Ultra-verlenging is nog niet open (ultra.extend_per_second is null); achteruit is nog niet open.
413	references_too_large	De voorbereide weergaven overschrijden het budget van de render: gebruik minder personages, of een kleiner formaat.
400	video_required, character_required	Een Face swap zonder video_b64, of zonder character_id.
413	video_too_large	Een Face swap-video groter dan 20 MB: trim of comprimeer hem eerst, of gebruik de MCP-tool tendre_face_swap, die tot 95 MB accepteert.
415	unreadable_video	De Face swap-video is geen leesbare MP4, MOV, WebM of MKV.
400	invalid_start, invalid_duration, passage_too_short	Een Face swap-fragment buiten de grenzen: start onder 0 of voorbij het einde van de video; duration buiten 0,5 tot 20 s; een fragment korter dan een halve seconde.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Een Face swap-veld buiten de grenzen: zone anders dan tight, normal of wide; part anders dan full of head; likeness buiten 0,5 tot 2; scene langer dan 400 tekens; description langer dan 360; name langer dan 60.
413	face_swap_too_large	Het fragment is na voorbereiding nog te zwaar: geef een kortere duration op.
429	server_busy	Onze server bereidt al twee Face swap-video's voor: probeer het opnieuw na Retry-After (20 s). De MCP-uploadlink geeft dezelfde code terug als 503 als er te veel bestanden wachten: probeer het over een paar minuten opnieuw.
503	face_swap_unavailable, face_swap_price_missing	Face swap is gesloten, of heeft momenteel geen prijs: probeer het later opnieuw.
503	creation_unavailable, multiref_unavailable, storage_unavailable	De service is momenteel niet beschikbaar: probeer het later opnieuw.
500	internal_error	Een onverwachte storing aan de serverzijde: probeer het opnieuw en laat het ons weten als het opnieuw gebeurt.

Ultra per seconde (Ultra):

Code	error	Wat het betekent en wat je moet doen
400	resolution_outside_ultra	Boven 1080p: 480p, 720p of 1080p.
400	engine_refused	De engine weigert de tekst of een beeld: de reden staat in detail en de code in code. Er wordt niets afgeschreven: herformuleer.
502	engine_unavailable	De engine antwoordt niet: probeer het over een paar minuten opnieuw. Er wordt niets afgeschreven.
409	render_in_progress	Annulering van een render die al wordt berekend: hij stopt niet meer, hij wordt geleverd en gefactureerd.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref in Ultra: een referentiebeeld is onleesbaar of te zwaar (in totaal hoogstens 20 MB), of een optie wordt niet ondersteund.
403	multiref_ultra_unavailable	Multi-Ref in Ultra per seconde is nog niet open voor dit account.

De foutnamen zijn de exacte strings die de API teruggeeft. Vergelijk op die namen, niet op de boodschap, die kan worden aangepast.

Eén antwoord is geen fout: een Multi-Ref-render of een Face swap met een personage dat slechts één weergave heeft, wordt verwerkt met een limited_likeness-waarschuwing in warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). De gelijkenis is beperkt: maak de zeven weergaven van het personage aan voor een getrouwe gelijkenis.

Een Multi-Ref-render in Ultra met 9 tot 12 personages wordt ook verwerkt, met een many_characters-waarschuwing: sommige kunnen ontbreken of door elkaar lopen (8 worden aanbevolen).

Best practices

• Peil elke 3 seconden, niet vaker. De wachtrij is gedeeld en hameren helpt niemand.
• Download zodra de status completed is. Het bestand wordt niet gearchiveerd.
• Schrijf prompts in het Engels en beschrijf voor video's de beweging in plaats van het stilstaande beeld.
• Eén sleutel per gebruik, en een dagelijks creditlimiet op elke sleutel die op een server staat. Een gelekte sleutel met een limiet kost je één dag, niet je hele saldo.
• Behandel een 429 als normaal, niet als een fout: wacht op Retry-After en ga verder.
• Een verbinding die wegvalt vóór het antwoord kost niets. Blijft een inzending van een afbeelding of video zonder antwoord (time-out van een proxy, fout 524, programma gestopt), dan wordt de render niet gestart, of meteen geannuleerd, en er wordt niets in rekening gebracht: stuur het verzoek gewoon opnieuw. Bij een reeks afbeeldingen (count) worden de al aangemaakte renders ook geannuleerd. Het aanmaken van een personage loopt wel door: hetzelfde verzoek opnieuw sturen geeft hetzelfde personage terug, zonder iets twee keer in rekening te brengen (zie Personages).

Prompts worden aan onze kant gelogd, net als voor de app, voor veiligheidsdoeleinden.