Pro API: grænser, fejlkoder og god praksis

Grænser

Hver nøgle har tre: renders på én gang (2 som standard), indsendelser per minut (60 som standard) og, hvis du sætter en, et dagligt kreditloft.

Overskrides en grænse, er svaret 429 med en Retry-After-header i sekunder. Et afvist kald koster ingenting. Den dag der bruges til grænserne er UTC-dagen.

Lange videoer tilføjer to egne grænser: 30 shots per sekvens og 5 sekvenser i gang per licens (se Videos).

Karakterer har én: 50 per Pro-licens, inklusive dem der er lavet i appen, og en karakter der ikke bruges i ét år slettes (se Characters). Lokationer, objekter og dyr har deres egne, talt separat: 50 per Pro-licens (10 med en personlig licens, i appen), slettet efter det samme år uden brug (se Lokationer, objekter, dyr, stilarter og outfits).

Face swap har to egne: et afsnit på maks. 20 s per render, og vores server forbereder to videoer ad gangen. Overskrides det, er svaret 429 server_busy: forsøg igen efter Retry-After (se Face swap). Via MCP tager en Face swap med overgang en hel video på højst 60 s, og serveren håndterer to ad gangen: derudover beder værktøjet om et nyt forsøg om et par minutter.

Vores eget kort deles med appens brugere. Når det er optaget, sendes dine renders til lejede GPU'er, til samme pris og via den samme API, med nogle titals sekunder ekstra ved opstart.

Fejlkoder

Kode	error	Hvad det betyder, og hvad du skal gøre
400	prompt_required	Tilføj et prompt.
400	forbidden_content	Indholdsfiltrene afviste promptet.
400	invalid_seed	seed skal være et helt tal fra 0 til 4294967295.
400	image_required, inpaint_images_required	Tilstanden kræver image_b64, og mask_b64 til inpaint.
401	key_required, invalid_key	Header mangler, eller ukendt nøgle.
402	insufficient_credits	Ikke nok saldo til denne render (cost opgives). Svaret indeholder buy_url, siden til køb af kreditter for din licens. En render eller en træning i gang reserverer sin pris indtil den slutter: engaged angiver, hvor mange kreditter der holdes tilbage på den måde.
402	confirmation_required, payment_declined	Et køb med dit gemte kort (POST /credits/purchase): din bank beder om din bekræftelse eller har afvist betalingen. Brug buy_url, det almindelige købslink.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Et køb med dit gemte kort: din agent må ikke købe (automatisk optankning på din kontoside), der er ikke gemt noget kort, eller købet ville overskride din månedlige grænse. Brug buy_url.
409	topup_in_progress, purchase_in_progress	En anden betaling med dit gemte kort er i gang: vent, til den er færdig.
400	unknown_pack	Et køb med en ukendt pakke, eller et valgfrit antal uden for grænserne eller ikke i hele trin.
503	payment_unavailable	Betalingen kunne ikke bekræftes: vi ved ikke, om trækket gik igennem. Prøv ikke igen med det samme; et træk, der gik igennem, bliver krediteret.
403	key_disabled, key_revoked, key_expired	Nøgle slukket, tilbagekaldt eller udløbet: opret en ny i appen.
403	license_revoked, license_not_pro	Licens tilbagekaldt, eller en konto der ikke er Pro.
403	missing_scope	Nøglen mangler den adgang der anmodes om, angivet i scope.
403	unknown_lora	En karakter der ikke tilhører kontoen.
404	media_unavailable	Filen er væk: send igen.
404	unknown_lora	Ved DELETE /loras/{name}, ingen fil med det navn på kontoen. Bemærk koden: det samme navn svarer 403, når en render anmoder om en karakter der ikke er din.
411	size_required	En LoRA-upload uden Content-Length. Brødteksten er rå, så størrelsen skal oplyses.
413	file_too_large	En LoRA over 800 MB, eller over 90 MB i en enkelt upload. Send den i dele. En ren 413 uden JSON-brødtekst er noget andet: anmodningen nåede aldrig API'et, se upload-afsnittet.
413	part_too_large	En del er større end den max_part_size sessionen meldte.
404	unknown_upload_session	uploadId eksisterer ikke, eller sessionen blev opgivet (seks timer) eller annulleret af en afvist del.
503	upload_refused, part_refused	Lageret kunne ikke nås under uploaden: forsøg igen.
507	storage_full	Ingen plads tilbage på serverlageret (LoRA'er eller sekvenser i gang). Teamet er advaret: forsøg igen senere.
415	invalid_safetensors	Den uploadede fil er ikke et safetensors-format.
415	incompatible_lora	LoRA'en er til en anden arkitektur, angivet i architecture. Billeder bruger kun Krea 2, videoer LTX 2.5 eller 2.3. Intet gemmes, og ingen kvote bruges.
413	lora_quota	Kontoens LoRA-lager er fuldt (20 filer eller 10 GB). Svaret angiver hvad der er tilbage; slet en fil for at frigøre plads.
413	image_too_large	Kildebillede eller maske over 12 MB afkodet.
429	too_many_concurrent_renders, rate_limited, daily_cap	En grænse er nået, se Retry-After.
429	daily_credit_cap	Nøglens daglige kreditloft er nået (cap, spent, cost).
502	submission_failed, status_failed	En hændelse på render-siden: forsøg igen om et par sekunder.
503	license_check_failed	Kontoen kan ikke tjekkes lige nu: forsøg igen om et minut.
400	invalid_extend_frames	En udvidelse hvis extend_frames ikke er 9, 17, 25, 33, 41 eller 49, eller en extend_video der ikke har præcis det antal frames.
400	extension_with_transition	En udvidelse kan ikke samtidig være en overgang, undtagen med consistency enhanced: fjern end_image, eller anmod om enhanced consistency.
400	extension_too_short	length for en udvidelse tæller kun de nye frames og skal være mindst 9.
404	clip_unavailable	Det klip der skal udvides er ikke længere tilgængeligt: udvid det hurtigere, eller send dets slutning i extend_video. Som 502 mislykkedes læsningen: forsøg igen.
404	unknown_clip	Det klip der skal udvides tilhører en anden licens.
404	unknown_sequence	Sekvensen eksisterer ikke, tilhører en anden licens eller er udløbet.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips uden et job_id, eller eksporten af en sekvens der ikke har noget shot.
409	not_exported_yet	GET /sequences/{id}/file før eksporten: kald POST /sequences/{id}/export først.
404	unknown_export	Eksport af projektmappen: ukendt rendering, fra en anden licens eller indsendt for mere end 24 t siden; ZIP-filen slettet (45 min efter første download, højst 2 t).
409	export_in_progress	Én eksport af projektmappe ad gangen pr. licens.
413	export_too_large	Projektmappe over 2 GB: eksportér skuddene ét ad gangen.
400	unknown_reference	Eksport af projektmappen: en post i exclude_references peger ikke på nogen reference i eksporten (hverken id, navn eller @omtale).
400	invalid_export_options	Eksport af projektmappen: et valg, der ikke er en boolesk værdi, en exclude_references, der ikke er en liste af tekster, eller include_film uden include_media.
500	export_failed	Eksporten mislykkedes (årsag i detail): intet trækkes, prøv igen.
422	resolution_mismatch, unreadable_clip	En render indsendt manuelt (POST /sequences/{id}/clips) med en anden opløsning end sekvensens, eller ulæselig.
409	missing_shot	Et shot er endnu ikke færdigt, eller ikke længere tilgængeligt (job_id angiver det): vent til det er færdigt, og eksporter derefter igen.
409	sequence_exported	Sekvensen er allerede samlet.
409	audio_mismatch	Et shot med lyd i en lydløs sekvens, eller omvendt.
413	extend_video_too_large	Klipafslutningen du sendte er over 8 MB.
413	too_many_shots	Maks. 30 shots per sekvens.
422	unreadable_tail	Klipafslutningen, sendt eller læst tilbage, er ikke en læsbar video.
422	assembly_failed	Shots har forskellige opløsninger, eller lyd på kun nogle af dem.
503	ultra_unavailable	Ultra-tilstand er lukket i øjeblikket: forsøg igen senere, eller render uden quality.
503	ultra_4k_unavailable	En 4K-størrelse anmodet i Ultra: 4K tilbydes ikke længere, video går op til 1080p (1920 x 1088).
400	ultra_incompatible	En overgang (end_image) anmodet i Ultra.
400	extension_4k	Fortsættelsen af et ældre 4K-klip: 4K tilbydes ikke længere, et 4K-klip kan ikke forlænges (ultra_4k_unavailable med quality: "max"). Forlæng et klip på højst 1080p.
400	resolution_above_quality	En størrelse over 1080p (1920 x 1088) uden quality: "max": 1080p er loftet i alle tilstande.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Keyframes uden for grænserne: mere end 4, et ugyldigt billede eller strength; et tidspunkt uden for klippet, eller to keyframes mindre end 0,5 s fra hinanden; en anden tilstand end Quality (Ultra, Multi-Ref), eller en udvidelse uden consistency enhanced.
400	invalid_consistency, consistency_mode	consistency andet end standard eller enhanced; enhanced consistency anmodet i Ultra eller i Multi-Ref.
400	consistency_explicit	Et prompt som enhanced consistency endnu ikke renderer, over 20 s (15 s med et end_image), i en udvidelse eller i en sekvens (et enkelt kortere shot renderes i standard consistency): gør det kortere, eller brug standard.
403	consistency_licensed_only	Enhanced consistency er forbeholdt licenser.
503	consistency_unavailable	Enhanced consistency er lukket i øjeblikket: forsøg igen senere, eller render i standard.
409	consistency_mismatch	Et shot hvis consistency adskiller sig fra sekvensens.
422	encoding_mismatch	En render indsendt manuelt (POST /sequences/{id}/clips) hvis consistency adskiller sig fra de allerede indsendte shots.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	En billedhastighed (fps) tilstanden ikke har (detail lister dem den har); enhanced consistency over 30 fps med automatisk varighed (sæt duration_auto til false og angiv length); en udvidelse med en anden billedhastighed end det forrige klips.
409	sequence_fps_mismatch	Et shot hvis billedhastighed (fps) adskiller sig fra sekvensens.
503	keyframes_unavailable	Keyframes er lukket i øjeblikket: render uden keyframes.
429	too_many_sequences	Maks. 5 sekvenser i gang per licens: eksporter én, eller vent på at én udløber.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Et karakterfelt uden for grænserne (se Characters).
400	image_too_small	Et foto under 1024 px på den lange side.
415	unsupported_image_format, unreadable_image	Et foto eller et lokationsbillede der ikke er en læsbar JPEG, PNG eller WebP.
404	unknown_character	character_id er ikke på din licens, eller blev slettet (ét år uden brug, eller slettet i appen).
409	character_limit	Karaktergrænsen (max) er nået: slet én.
409	character_busy	Dens visninger er ved at blive lavet: vent til status ikke længere er pending. Ved POST /characters: den samme oprettelse er ved at blive gemt, send den igen nogle sekunder senere.
409	photo_view, empty_character, single_image_sheet	Den visning der kom fra det originale foto kan ikke genskabes; eller karakteren har ingen læsbar visning (hvis det er lageret, der afviser læsningen: 503 storage_unavailable, prøv igen); eller et sheet importeret som ét billede (bevaret som det er): dets visninger laves ikke om, og det klæder ikke et nyt sheet på (send visning 4 eller 1).
409	app_character	En instruction eller en uploadet visning på en karakter eller en character sheet fra appen: forbeholdt karakterer og character sheets oprettet via API'et.
400	instruction_too_long	En instruction længere end 200 tegn.
400	outfit_or_views_required	En character sheet tilføjet uden outfit og uden views: angiv et outfit at generere, eller vinkler.
400	views_required	En character sheet tilføjet med generate: false: angiv mindst én vinkel.
409	source_sheet_empty	En character sheet tilføjet uden helkropsvinkel og uden buste til en karakter, der ingen af dem har at tage udgangspunkt i: send en af dem i views.
404	unknown_sheet	Kun en character sheet tilføjet via API'et (sheet_origin api) kan slettes med DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	subject_id er ikke på din licens, eller blev slettet efter ét år uden brug.
409	subject_limit	Grænsen for subjects (max) er nået: lokationer, objekter, dyr, stilarter og outfits tælles sammen; slet ét.
409	empty_subject	Et subject uden noget læsbart billede.
400	invalid_type, description_too_long, invalid_images	Et subject-felt uden for grænserne (se Lokationer, objekter, dyr, stilarter og outfits).
400	invalid_image	Et subject-billede der ikke er en læsbar JPEG, PNG eller WebP på mindst 512 px på den lange side (index angiver hvilket).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Generér et subject: hverken description, prompt eller startbillede; en visningsnøgle, som typen ikke har (detail giver listen); count uden for 1 til 6, eller flere end 6 billeder, start medregnet; en prompt på over 2.000 tegn; instructions tomme, for lange eller til flere visninger.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	Der kører allerede en serie på dette subject; et subject lavet ud fra billeder (tilføj billeder via /images); en visning, der allerede er lavet (lav den om); en start, der skal laves om, mens visninger tager udgangspunkt i den; en mislykket start, der først skal laves om; en importeret start, som ikke kan laves om.
404 / 503	unknown_view, generation_unavailable	En visning, der aldrig er bedt om (tilføj den); generering af subjects er ikke tilgængelig på serveren i øjeblikket: prøv igen senere.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref uden for grænserne: 1 til 4 karakterer (12 i Ultra), ingen udvidelse eller overgang, formaterne og længderne for Multi-Ref Video.
400	duplicate_name, invalid_strength, unknown_mention	To karakterer med samme navn; strength uden for 0 til 2; et @Navn i promptet uden en karakter (mentions lister dem).
400	voice_requires_audio, voice_slot	En karakterstemme (voice_b64) uden lyd ("audio": true); eller på en anden karakter end characters[0] og characters[1] (motoren understøtter 2 stemmer). index angiver hvilken.
400	invalid_voice_choice	voice andet end character eller original i et Face swap, eller characters[].voice andet end character eller generated i Multi-Ref Video.
413	audio_too_large	En karakterstemme over 4 MB, eller over 2 MB i et Face swap. Kun de første 5 sekunder bruges (20 i et Face swap): send et kort uddrag.
415	unsupported_audio_format	En karakterstemme der ikke er en læsbar lydfil (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Mere end 4 karakterer, objekter og dyr tilsammen uden for Ultra; et subject i det forkerte felt (en lokation i subjects, et objekt som location, en stil uden for styles, et outfit uden for outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Create an image: count 1 eller 2, view 1 til 5 og til stede i character sheet, lora_pass 0,3 til 0,9, image for et subject blandt dets billeder, bredde og højde fra 256 til 2048.
400	character_not_ready	Create an image: den valgte vinkel for en karakter har endnu intet billede.
503	multiref_image_disabled	Create an image er endnu ikke åbnet på denne server.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Stilarter, outfits eller bevægelse uden for Multi-Ref i Ultra; mere end 30 billeder i Ultra; en worn_by, der ikke navngiver nogen karakter.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion uden motion_id og uden video_b64; en anden mode end camera eller choreography; en ulæselig video, eller en uden for 4 til 30 s (input_video_out_of_limits); et motion_id, der aldrig er uploadet (intet PUT).
404 / 409	unknown_motion, motion_already_used	Et motion_id, der er ukendt, allerede brugt eller ældre end 2 timer: upload videoen igen.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	En bevægelsesvideo over 20 MB (20 MB, når den er nedskaleret til 480p); bevægelsen er ikke åbnet endnu (ultra.motion_per_second er null); en mode, der ikke er åbnet endnu.
409	extension_link_expired	Et extend_job_id, som din licens ikke kender, eller et Ultra-skud ældre end 24 timer: upload dets original (POST /extensions) og send extend_upload_id.
400	extension_real_face	Videoen, der skal forlænges i Ultra, er ikke renderet i Ultra-tilstand (for eksempel en rendering fra en anden tilstand) og viser et realistisk ansigt: intet trækkes. Forlæng den i Quality-tilstand, eller lav skuddet om i Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Ultra-forlængelse uden for grænserne: extend_upload_id eller backward uden quality: "max" (eller fra et klip, der ikke er Ultra); et startbillede, referencer, bevægelse eller forbedret konsistens samtidig; en anden retning end forward eller backward; backward i en sekvens; extend_video i Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	En uploadet video over 1080p; en ulæselig MP4, eller en uden for 4 til 30 s (input_video_out_of_limits); en fil, der aldrig er uploadet (intet PUT).
400	input_video_out_of_limits	En video, der sendes til Ultra-tilstanden (bevægelse, video, der skal forlænges), uden for grænserne, kontrolleret før renderingen, intet trukket: limit angiver hvilken (duration: 4 til 30 s; total_duration: 30 s med referencelydene; count: 10; size: 200 MB; format: MP4 eller MOV; fps: 24 til 60; pixels: bredde × højde fra 409.600 til 8.295.044; aspect_ratio: 0,4 til 2,5), med value, min og max.
404 / 409	unknown_extension_upload, extension_upload_used	Et extend_upload_id, der er ukendt, ældre end 2 timer eller allerede brugt: upload filen igen.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	En fil over 60 MB; Ultra-forlængelsen er ikke åbnet endnu (ultra.extend_per_second er null); bagud er ikke åbnet endnu.
413	references_too_large	De forberedte visninger overskrider renderens budget: færre karakterer, eller et mindre format.
400	video_required, character_required	Et Face swap uden video_b64, eller uden character_id.
413	video_too_large	En Face swap-video over 20 MB: klip eller komprimer den først, eller brug MCP-værktøjet tendre_face_swap, som håndterer op til 95 MB.
415	unreadable_video	Face swap-videoen er ikke en læsbar MP4, MOV, WebM eller MKV.
400	invalid_start, invalid_duration, passage_too_short	Et Face swap-afsnit uden for grænserne: start under 0 eller efter videoens slutning; duration uden for 0,5 til 20 s; et afsnit kortere end et halvt sekund.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Et Face swap-felt uden for grænserne: zone andet end tight, normal eller wide; part andet end full eller head; likeness uden for 0,5 til 2; scene over 400 tegn; description over 360; name over 60.
413	face_swap_too_large	Afsnittet er stadig for tungt efter forberedelse: angiv en kortere duration.
429	server_busy	Vores server forbereder allerede to Face swap-videoer: forsøg igen efter Retry-After (20 s). MCP-uploadlinket svarer med samme kode som en 503, når der venter for mange filer: forsøg igen om et par minutter.
503	face_swap_unavailable, face_swap_price_missing	Face swap er lukket, eller har ingen pris, i øjeblikket: forsøg igen senere.
503	creation_unavailable, multiref_unavailable, storage_unavailable	Tjenesten er utilgængelig i øjeblikket: forsøg igen senere.
500	internal_error	En uventet hændelse på serverside: forsøg igen, og fortæl os det, hvis det sker igen.

Ultra pr. sekund (Ultra):

Kode	error	Hvad det betyder, og hvad du skal gøre
400	resolution_outside_ultra	Over 1080p: 480p, 720p eller 1080p.
400	engine_refused	Motoren afviser teksten eller et billede: årsagen står i detail og koden i code. Intet trækkes: omformuler.
502	engine_unavailable	Motoren svarer ikke: prøv igen om nogle minutter. Intet trækkes.
409	render_in_progress	Annullering af en gengivelse, der allerede beregnes: den stopper ikke længere, den leveres og afregnes.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref i Ultra: et referencebillede er ulæseligt eller for tungt (højst 20 MB i alt), eller en indstilling understøttes ikke.
403	multiref_ultra_unavailable	Multi-Ref i Ultra pr. sekund er endnu ikke åbent for denne konto.

Fejlnavnene er de præcise strenge API'et returnerer. Match på dem frem for på beskeden, som kan blive omformuleret.

Et svar er ikke en fejl: en Multi-Ref-render eller et Face swap med en karakter der kun har én visning, gennemføres med en limited_likeness-advarsel i warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). Ligheden er begrænset: opret karakterens syv visninger for en trofast gengivelse.

En Multi-Ref-render i Ultra med 9 til 12 karakterer gennemføres også, med en many_characters-advarsel: nogle kan mangle eller blive blandet sammen (8 anbefales).

God praksis

• Poll hvert 3. sekund, ikke hurtigere. Køen er delt, og det hjælper ingen at hamre løs på den.
• Download så snart status er completed. Filen arkiveres ikke.
• Skriv prompts på engelsk, og til videoer beskriv bevægelsen frem for stilbilledet.
• Én nøgle per anvendelse, og et dagligt kreditloft på hver nøgle der lever på en server. En lækket nøgle med et loft koster dig én dag, ikke hele saldoen.
• Behandl en 429 som noget normalt, ikke som en fejl: vent på Retry-After og fortsæt.
• En forbindelse, der afbrydes før svaret, koster intet. Hvis en indsendelse af et billede eller en video forbliver uden svar (en proxys tidsgrænse overskredet, fejl 524, programmet stoppet), startes renderingen ikke, eller den annulleres med det samme, og der opkræves intet: send blot anmodningen igen. For en serie billeder (count) annulleres de allerede oprettede renderinger også. Oprettelsen af en karakter fortsætter derimod: sender du den samme anmodning igen, får du den samme karakter tilbage, uden at noget opkræves to gange (se Characters).

Prompts logges på vores side, ligesom det sker for appen, af sikkerhedsmæssige årsager.