Pro API: grenser, feilkoder og god praksis

Grenser

Hver nøkkel har tre: samtidige rendringer (2 som standard), innsendinger per minutt (60 som standard) og, hvis du setter en, en daglig kredittgrense.

Når en grense nås, er svaret 429 med en Retry-After-header i sekunder. Et avvist kall koster ingenting. Dagen som brukes for grensene er UTC-dagen.

Lange videoer legger til to egne grenser: 30 klipp per sekvens og 5 sekvenser i gang per lisens (se Videos).

Karakterer har én: 50 per Pro-lisens, inkludert de som er laget i appen, og en karakter som ikke har vært i bruk på ett år blir slettet (se Characters). Steder, objekter og dyr har sine egne, talt separat: 50 per Pro-lisens (10 med en personlig lisens, i appen), slettet etter samme år uten bruk (se Steder, objekter, dyr, stiler og antrekk).

Face swap har to egne: et utsnitt på maks 20 s per rendring, og serveren vår forbereder to videoer om gangen. Etter det er svaret 429 server_busy: prøv igjen etter Retry-After (se Face swap). Via MCP tar en Face swap med overgang en hel video på maks 60 s, og serveren håndterer to om gangen: utover det ber verktøyet om et nytt forsøk om noen minutter.

Vårt eget kort deles med appens brukere. Når det er opptatt, går rendringene dine til leide GPU-er, til samme pris og gjennom samme API, med noen titalls sekunder ekstra ved oppstart.

Feilkoder

Kode	error	Hva det betyr, og hva du gjør
400	prompt_required	Legg til en prompt.
400	forbidden_content	Innholdsfilter avviste prompten.
400	invalid_seed	seed må være et helt tall fra 0 til 4294967295.
400	image_required, inpaint_images_required	Modusen trenger image_b64, og mask_b64 for inpaint.
401	key_required, invalid_key	Header mangler, eller ukjent nøkkel.
402	insufficient_credits	Ikke nok saldo for denne rendringen (cost oppgis). Svaret inneholder buy_url, siden for kjøp av kreditter til lisensen din. En rendring eller opplæring som er i gang reserverer prisen sin til den er ferdig: engaged sier hvor mange kreditter som holdes av på den måten.
402	confirmation_required, payment_declined	Et kjøp med det lagrede kortet ditt (POST /credits/purchase): banken din ber om bekreftelse, eller har avvist betalingen. Bruk buy_url, den vanlige kjøpslenken.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Et kjøp med det lagrede kortet ditt: agenten din har ikke lov til å kjøpe (automatisk påfyll på kontosiden din), ingen kort er lagret, eller kjøpet ville gått over månedsgrensen din. Bruk buy_url.
409	topup_in_progress, purchase_in_progress	En annen betaling med det lagrede kortet ditt pågår: vent til den er ferdig.
400	unknown_pack	Et kjøp med en ukjent pakke, eller et valgfritt antall utenfor grensene eller ikke i hele trinn.
503	payment_unavailable	Betalingen kunne ikke bekreftes: vi vet ikke om trekket gikk gjennom. Ikke prøv igjen med en gang; et trekk som gikk gjennom blir kreditert.
403	key_disabled, key_revoked, key_expired	Nøkkelen er slått av, tilbakekalt eller utløpt: opprett en ny i appen.
403	license_revoked, license_not_pro	Lisensen er tilbakekalt, eller kontoen er ikke Pro.
403	missing_scope	Nøkkelen mangler tillatelsen som ble bedt om, navngitt i scope.
403	unknown_lora	En karakter som ikke tilhører kontoen.
404	media_unavailable	Filen er borte: send inn på nytt.
404	unknown_lora	Ved DELETE /loras/{name}: ingen fil med det navnet på kontoen. Merk koden: samme navn svarer 403 når en rendring ber om en karakter som ikke er din.
411	size_required	En LoRA-opplasting uten Content-Length. Innholdet er rådata, så størrelsen må oppgis på forhånd.
413	file_too_large	En LoRA over 800 MB, eller over 90 MB i én enkelt opplasting. Send den i deler. En ren 413 uten JSON-innhold er noe annet: forespørselen nådde aldri API-et, se opplastingsdelen.
413	part_too_large	En del er større enn max_part_size som sesjonen oppga.
404	unknown_upload_session	uploadId finnes ikke, eller sesjonen ble forlatt (seks timer) eller avbrutt av en avvist del.
503	upload_refused, part_refused	Lagringen kunne ikke nås under opplastingen: prøv igjen.
507	storage_full	Ikke mer plass på serverlagringen (LoRA-er eller sekvenser i gang). Teamet er varslet: prøv igjen senere.
415	invalid_safetensors	Den opplastede filen er ikke en safetensors.
415	incompatible_lora	LoRA-en er for en annen arkitektur, navngitt i architecture. Bilder bruker kun Krea 2, videoer LTX 2.5 eller 2.3. Ingenting lagres og ingen kvote brukes.
413	lora_quota	Kontoens LoRA-lagring er full (20 filer eller 10 GB). Svaret sier hva som gjenstår; slett en fil for å frigjøre plass.
413	image_too_large	Kildebilde eller maske over 12 MB dekomprimert.
429	too_many_concurrent_renders, rate_limited, daily_cap	En grense er nådd, se Retry-After.
429	daily_credit_cap	Nøkkelens daglige kredittgrense er nådd (cap, spent, cost).
502	submission_failed, status_failed	En hendelse på rendringssiden: prøv igjen om noen sekunder.
503	license_check_failed	Kontoen kan ikke sjekkes akkurat nå: prøv igjen om et minutt.
400	invalid_extend_frames	En forlengelse der extend_frames ikke er 9, 17, 25, 33, 41 eller 49, eller en extend_video som ikke har nøyaktig så mange frames.
400	extension_with_transition	En forlengelse kan ikke samtidig være en overgang, unntatt med consistency enhanced: fjern end_image, eller be om enhanced consistency.
400	extension_too_short	length for en forlengelse teller kun de nye framene og må være minst 9.
404	clip_unavailable	Klippet som skal forlenges er ikke lenger tilgjengelig: forleng det raskere, eller send slutten i extend_video. Som 502 mislyktes lesingen: prøv igjen.
404	unknown_clip	Klippet som skal forlenges tilhører en annen lisens.
404	unknown_sequence	Sekvensen finnes ikke, tilhører en annen lisens, eller har utløpt.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips uten job_id, eller eksport av en sekvens uten noe klipp.
409	not_exported_yet	GET /sequences/{id}/file før eksporten: kall POST /sequences/{id}/export først.
404	unknown_export	Eksport av prosjektmappen: ukjent rendring, fra en annen lisens eller sendt inn for mer enn 24 t siden; ZIP-filen slettet (45 min etter første nedlasting, maks 2 t).
409	export_in_progress	Én eksport av prosjektmappe om gangen per lisens.
413	export_too_large	Prosjektmappe over 2 GB: eksporter klippene ett og ett.
400	unknown_reference	Eksport av prosjektmappen: en oppføring i exclude_references peker ikke på noen referanse i eksporten (verken id, navn eller @omtale).
400	invalid_export_options	Eksport av prosjektmappen: et valg som ikke er en boolsk verdi, en exclude_references som ikke er en liste med tekster, eller include_film uten include_media.
500	export_failed	Eksporten mislyktes (årsak i detail): ingenting trekkes, prøv igjen.
422	resolution_mismatch, unreadable_clip	En rendring lagt inn manuelt (POST /sequences/{id}/clips) med en annen oppløsning enn sekvensens, eller uleselig.
409	missing_shot	Et klipp er ikke ferdig ennå, eller er ikke lenger tilgjengelig (job_id navngir det): vent til det er ferdig, eksporter deretter på nytt.
409	sequence_exported	Sekvensen er allerede satt sammen.
409	audio_mismatch	Et klipp med lyd i en stum sekvens, eller omvendt.
413	extend_video_too_large	Klippslutten du sendte er over 8 MB.
413	too_many_shots	Maks 30 klipp per sekvens.
422	unreadable_tail	Klippslutten, sendt eller lest tilbake, er ikke en leselig video.
422	assembly_failed	Klippene har forskjellige oppløsninger, eller lyd på bare noen av dem.
503	ultra_unavailable	Ultra-modus er stengt for øyeblikket: prøv igjen senere, eller rendre uten quality.
503	ultra_4k_unavailable	En 4K-størrelse bedt om i Ultra: 4K tilbys ikke lenger, video går opp til 1080p (1920 x 1088).
400	ultra_incompatible	En overgang (end_image) bedt om i Ultra.
400	extension_4k	Forlengelse av et eldre 4K-klipp: 4K tilbys ikke lenger, et 4K-klipp kan ikke forlenges (ultra_4k_unavailable med quality: "max"). Forleng et klipp på maks 1080p.
400	resolution_above_quality	En størrelse over 1080p (1920 x 1088) uten quality: "max": 1080p er taket i alle moduser.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Keyframes utenfor grensene: mer enn 4, ugyldig bilde eller styrke; et tidspunkt utenfor klippet, eller to keyframes mindre enn 0,5 s fra hverandre; en annen modus enn Quality (Ultra, Multi-Ref), eller en forlengelse uten consistency enhanced.
400	invalid_consistency, consistency_mode	consistency annet enn standard eller enhanced; enhanced consistency bedt om i Ultra eller i Multi-Ref.
400	consistency_explicit	En prompt som enhanced consistency ikke rendrer ennå, over 20 s (15 s med end_image), i en forlengelse eller i en sekvens (ett kortere enkeltklipp rendres i standard consistency): forkort den, eller bruk standard.
403	consistency_licensed_only	Enhanced consistency er forbeholdt lisenser.
503	consistency_unavailable	Enhanced consistency er stengt for øyeblikket: prøv igjen senere, eller rendre i standard.
409	consistency_mismatch	Et klipp der consistency avviker fra sekvensens.
422	encoding_mismatch	En rendring lagt inn manuelt (POST /sequences/{id}/clips) der consistency avviker fra klippene som allerede er lagt inn.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	En bilderate (fps) modusen ikke har (detail lister de tilgjengelige); enhanced consistency over 30 fps med automatisk varighet (sett duration_auto til false og oppgi length); en forlengelse med en annen bilderate enn forrige klipp.
409	sequence_fps_mismatch	Et klipp der bilderaten (fps) avviker fra sekvensens.
503	keyframes_unavailable	Keyframes er stengt for øyeblikket: rendre uten keyframes.
429	too_many_sequences	Maks 5 sekvenser i gang per lisens: eksporter én, eller vent på at én utløper.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Et karakterfelt utenfor grensene (se Characters).
400	image_too_small	Et foto under 1024 px på den lange siden.
415	unsupported_image_format, unreadable_image	Et foto eller et stedsbilde som ikke er en leselig JPEG, PNG eller WebP.
404	unknown_character	character_id er ikke på lisensen din, eller ble slettet (ett år uten bruk, eller slettet i appen).
409	character_limit	Karaktergrensen (max) er nådd: slett én.
409	character_busy	Visningene dens blir laget: vent til status ikke lenger er pending. Ved POST /characters: den samme opprettelsen holder på å lagres, send den på nytt noen sekunder senere.
409	photo_view, empty_character, single_image_sheet	Visningen som kom fra originalfotoet kan ikke gjøres om igjen; eller karakteren har ingen leselig visning (hvis det er lagringen som nekter lesingen: 503 storage_unavailable, prøv igjen); eller et sheet importert som ett enkelt bilde (beholdt som det er): visningene lages ikke på nytt, og det kler ikke et nytt sheet (send visning 4 eller 1).
409	app_character	En instruction eller en opplastet visning på en karakter eller en character sheet fra appen: forbeholdt karakterer og character sheets opprettet via API-et.
400	instruction_too_long	En instruction lengre enn 200 tegn.
400	outfit_or_views_required	En character sheet lagt til uten outfit og uten views: oppgi et antrekk å generere, eller visninger.
400	views_required	En character sheet lagt til med generate: false: oppgi minst én visning.
409	source_sheet_empty	En character sheet lagt til uten helfigursvisning og uten byste, på en karakter som ikke har noen av dem å starte fra: send en av dem i views.
404	unknown_sheet	Bare en character sheet lagt til via API-et (sheet_origin api) kan slettes med DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	subject_id er ikke på lisensen din, eller ble slettet etter ett år uten bruk.
409	subject_limit	Grensen for subjekter (max) er nådd: steder, objekter, dyr, stiler og antrekk telles sammen; slett ett.
409	empty_subject	Et subject uten leselig bilde.
400	invalid_type, description_too_long, invalid_images	Et subject-felt utenfor grensene (se Steder, objekter, dyr, stiler og antrekk).
400	invalid_image	Et subject-bilde som ikke er en leselig JPEG, PNG eller WebP på minst 512 px på den lange siden (index sier hvilken).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Generere et subjekt: verken description, prompt eller startbilde; en visningsnøkkel som typen ikke har (detail gir listen); count utenfor 1 til 6, eller flere enn 6 bilder, start inkludert; en prompt på over 2 000 tegn; instructions tomme, for lange eller for flere visninger.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	En serie kjører allerede på dette subjektet; et subjekt laget av bilder (legg til bilder via /images); en visning som allerede er laget (lag den på nytt); en start som skal lages på nytt mens visninger går ut fra den; en mislykket start som først må lages på nytt; en importert start, som ikke kan lages på nytt.
404 / 503	unknown_view, generation_unavailable	En visning som aldri er bedt om (legg den til); generering av subjekter er ikke tilgjengelig på serveren for øyeblikket: prøv igjen senere.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref utenfor grensene: 1 til 4 karakterer (12 i Ultra), ingen forlengelse eller overgang, formatene og lengdene for Multi-Ref Video.
400	duplicate_name, invalid_strength, unknown_mention	To karakterer med samme navn; strength utenfor 0 til 2; et @Navn i prompten uten tilhørende karakter (mentions lister dem).
400	voice_requires_audio, voice_slot	En karakterstemme (voice_b64) uten lyd ("audio": true); eller på en annen karakter enn characters[0] og characters[1] (motoren støtter 2 stemmer). index sier hvilken.
400	invalid_voice_choice	voice annet enn character eller original i en Face swap, eller characters[].voice annet enn character eller generated i Multi-Ref Video.
413	audio_too_large	En karakterstemme over 4 MB, eller over 2 MB i en Face swap. Kun de første 5 sekundene brukes (20 i en Face swap): send et kort utdrag.
415	unsupported_audio_format	En karakterstemme som ikke er en leselig lydfil (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Mer enn 4 karakterer, objekter og dyr totalt, utenom Ultra; et subjekt i feil felt (et sted i subjects, et objekt som location, en stil utenfor styles, et antrekk utenfor 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, et subjekts image blant bildene dets, bredde og høyde fra 256 til 2048.
400	character_not_ready	Create an image: den valgte visningen av en karakter har ikke noe bilde ennå.
503	multiref_image_disabled	Create an image er ikke åpnet på denne serveren ennå.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Stiler, antrekk eller bevegelse utenfor Multi-Ref i Ultra; mer enn 30 bilder i Ultra; en worn_by som ikke navngir noen karakter.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion uten motion_id og uten video_b64; en annen mode enn camera eller choreography; en uleselig video, eller en utenfor 4 til 30 s (input_video_out_of_limits); en motion_id som aldri ble lastet opp (ingen PUT).
404 / 409	unknown_motion, motion_already_used	En motion_id som er ukjent, allerede brukt eller eldre enn 2 timer: last opp videoen på nytt.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	En bevegelsesvideo over 20 MB (20 MB når den er skalert ned til 480p); bevegelsen er ikke åpnet ennå (ultra.motion_per_second er null); en mode som ikke er åpnet ennå.
409	extension_link_expired	En extend_job_id som lisensen din ikke kjenner, eller et Ultra-opptak eldre enn 24 timer: last opp originalen (POST /extensions) og send extend_upload_id.
400	extension_real_face	Videoen som skal forlenges i Ultra ble ikke rendret i Ultra-modus (for eksempel en rendering fra en annen modus) og viser et realistisk ansikt: ingenting belastes. Forleng den i Quality-modus, eller lag opptaket på nytt i Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Ultra-forlengelse utenfor grensene: extend_upload_id eller backward uten quality: "max" (eller fra et klipp som ikke er Ultra); et startbilde, referanser, bevegelse eller enhanced consistency samtidig; en annen retning enn forward eller backward; backward i en sekvens; extend_video i Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	En opplastet video over 1080p; en uleselig MP4, eller en utenfor 4 til 30 s (input_video_out_of_limits); en fil som aldri ble lastet opp (ingen PUT).
400	input_video_out_of_limits	En video som sendes til Ultra-modusen (bevegelse, video som skal forlenges) utenfor grensene, kontrollert før renderingen, ingenting trukket: limit sier hvilken (duration: 4 til 30 s; total_duration: 30 s med referanselydene; count: 10; size: 200 MB; format: MP4 eller MOV; fps: 24 til 60; pixels: bredde × høyde 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	En extend_upload_id som er ukjent, eldre enn 2 timer eller allerede brukt: last opp filen på nytt.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	En fil over 60 MB; Ultra-forlengelsen er ikke åpnet ennå (ultra.extend_per_second er null); bakover er ikke åpnet ennå.
413	references_too_large	De forberedte visningene overstiger rendringens budsjett: færre karakterer, eller et mindre format.
400	video_required, character_required	En Face swap uten video_b64, eller uten character_id.
413	video_too_large	En Face swap-video over 20 MB: klipp eller komprimer den først, eller bruk MCP-verktøyet tendre_face_swap, som tar opptil 95 MB.
415	unreadable_video	Face swap-videoen er ikke en leselig MP4, MOV, WebM eller MKV.
400	invalid_start, invalid_duration, passage_too_short	Et Face swap-utsnitt utenfor grensene: start under 0 eller etter slutten av videoen; duration utenfor 0,5 til 20 s; et utsnitt kortere enn et halvt sekund.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Et Face swap-felt utenfor grensene: zone annet enn tight, normal eller wide; part annet enn full eller head; likeness utenfor 0,5 til 2; scene over 400 tegn; description over 360; name over 60.
413	face_swap_too_large	Utsnittet er fortsatt for tungt etter forberedelse: oppgi en kortere duration.
429	server_busy	Serveren vår forbereder allerede to Face swap-videoer: prøv igjen etter Retry-After (20 s). MCP-opplastingslenken svarer med samme kode som en 503 når for mange filer venter: prøv igjen om noen minutter.
503	face_swap_unavailable, face_swap_price_missing	Face swap er stengt, eller har ingen pris, for øyeblikket: prøv igjen senere.
503	creation_unavailable, multiref_unavailable, storage_unavailable	Tjenesten er utilgjengelig for øyeblikket: prøv igjen senere.
500	internal_error	En uventet hendelse på serversiden: prøv igjen, og gi oss beskjed hvis det skjer igjen.

Ultra per sekund (Ultra):

Kode	error	Hva det betyr, og hva du gjør
400	resolution_outside_ultra	Over 1080p: 480p, 720p eller 1080p.
400	engine_refused	Motoren avviser teksten eller et bilde: årsaken står i detail og koden i code. Ingenting belastes: omformuler.
502	engine_unavailable	Motoren svarer ikke: prøv igjen om noen minutter. Ingenting belastes.
409	render_in_progress	Avbrudd av en rendering som allerede beregnes: den stopper ikke, den leveres og faktureres.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref i Ultra: et referansebilde er uleselig eller for tungt (maks 20 MB totalt), eller et alternativ støttes ikke.
403	multiref_ultra_unavailable	Multi-Ref i Ultra per sekund er ennå ikke åpent for denne kontoen.

Feilnavnene er de eksakte strengene API-et returnerer. Match på dem, ikke på meldingen, som kan bli omformulert.

Ett svar er ikke en feil: en Multi-Ref-rendring eller en Face swap med en karakter som bare har én visning går gjennom, med en limited_likeness-advarsel i warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). Likheten er begrenset: opprett karakterens sju visninger for en troverdig likhet.

En Multi-Ref-rendring i Ultra med 9 til 12 karakterer går også gjennom, med en many_characters-advarsel: noen kan mangle eller blandes sammen (8 anbefales).

God praksis

• Poll hvert 3. sekund, ikke raskere. Køen er delt, og å bombardere den hjelper ingen.
• Last ned så snart statusen er completed. Filen arkiveres ikke.
• Skriv prompts på engelsk, og for videoer: beskriv bevegelsen heller enn stillbildet.
• Én nøkkel per bruksområde, og en daglig kredittgrense på hver nøkkel som lever på en server. En lekket nøkkel med en grense koster deg én dag, ikke hele saldoen.
• Behandle en 429 som normalt, ikke som en feil: vent på Retry-After og fortsett.
• En tilkobling som brytes før svaret, koster ingenting. Hvis en innsending av bilde eller video blir uten svar (en proxys tidsgrense overskredet, feil 524, programmet stoppet), startes ikke rendringen, eller den avbrytes med en gang, og ingenting belastes: bare send forespørselen på nytt. For en serie bilder (count) avbrytes også rendringene som allerede er opprettet. Opprettelsen av en karakter fortsetter derimot: sender du den samme forespørselen på nytt, får du samme karakter tilbake, uten at noe belastes to ganger (se Characters).

Prompts logges hos oss, akkurat som for appen, av sikkerhetshensyn.