Pro API: begränsningar, felkoder och god praxis

Gränser

Varje nyckel har tre: renders samtidigt (2 som standard), anrop per minut (60 som standard) och, om du angett ett, ett dagligt kredittak.

När ett tak nås är svaret 429 med en Retry-After-header i sekunder. Ett avvisat anrop kostar ingenting. Den dag som gäller för taken är UTC-dagen.

Långa videor lägger till två egna tak: 30 klipp per sekvens och 5 sekvenser pågående per licens (se Videos).

Karaktärer har ett: 50 per Pro-licens, inklusive de som skapats i appen, och en karaktär som inte används på ett år raderas (se Characters). Platser, objekt och djur har sina egna, räknade separat: 50 per Pro-licens (10 med en personlig licens, i appen), raderade efter samma år utan användning (se Platser, objekt, djur, stilar och outfits).

Face swap har två egna: ett avsnitt på högst 20 s per render, och vår server förbereder två videor åt gången. Passeras det är svaret 429 server_busy: försök igen efter Retry-After (se Face swap). Via MCP tar en Face swap med övergång en hel video på max 60 s, och servern hanterar två åt gången: därutöver ber verktyget om ett nytt försök om några minuter.

Vårt eget kort delas med appens användare. När det är upptaget skickas dina renders till hyrda GPU:er, till samma pris och via samma API, med några tiotals sekunder extra vid uppstart.

Felkoder

Kod	error	Vad det betyder och vad du gör
400	prompt_required	Lägg till en prompt.
400	forbidden_content	Innehållsfiltret nekade prompten.
400	invalid_seed	seed måste vara ett heltal från 0 till 4294967295.
400	image_required, inpaint_images_required	Läget kräver image_b64, och mask_b64 för inpaint.
401	key_required, invalid_key	Header saknas, eller okänd nyckel.
402	insufficient_credits	Inte tillräckligt med saldo för den här rendern (cost anges). Svaret innehåller buy_url, sidan för köp av krediter för din licens. En render eller träning som pågår reserverar sitt pris tills den är klar: engaged anger hur många krediter som hålls åt sidan på det viset.
402	confirmation_required, payment_declined	Ett köp med ditt sparade kort (POST /credits/purchase): din bank begär din bekräftelse eller har nekat betalningen. Använd buy_url, den vanliga köplänken.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Ett köp med ditt sparade kort: din agent får inte köpa (automatisk påfyllning på din kontosida), inget kort är sparat, eller köpet skulle gå över din månadsgräns. Använd buy_url.
409	topup_in_progress, purchase_in_progress	En annan betalning med ditt sparade kort pågår: vänta tills den är klar.
400	unknown_pack	Ett köp med ett okänt paket, eller ett valfritt antal utanför gränserna eller inte i hela steg.
503	payment_unavailable	Betalningen kunde inte bekräftas: vi vet inte om debiteringen gick igenom. Försök inte igen direkt; en debitering som gick igenom krediteras.
403	key_disabled, key_revoked, key_expired	Nyckeln är avstängd, återkallad eller har gått ut: skapa en ny i appen.
403	license_revoked, license_not_pro	Licensen är återkallad, eller ett konto som inte är Pro.
403	missing_scope	Nyckeln saknar den begärda behörigheten, angiven i scope.
403	unknown_lora	En karaktär som inte tillhör kontot.
404	media_unavailable	Filen är borta: skicka in igen.
404	unknown_lora	Vid DELETE /loras/{name}, ingen fil med det namnet på kontot. Notera koden: samma namn svarar 403 när en render frågar efter en karaktär som inte är din.
411	size_required	En LoRA-uppladdning utan Content-Length. Innehållet är rått, så storleken måste anges i förväg.
413	file_too_large	En LoRA över 800 MB, eller över 90 MB i en enskild uppladdning. Skicka den i delar. En ren 413 utan JSON-innehåll är något annat: begäran nådde aldrig API:et, se uppladdningsavsnittet.
413	part_too_large	En del är större än det max_part_size som sessionen angav.
404	unknown_upload_session	uploadId finns inte, eller sessionen övergavs (sex timmar) eller avbröts av en nekad del.
503	upload_refused, part_refused	Lagringen kunde inte nås under uppladdningen: försök igen.
507	storage_full	Inget utrymme kvar på serverlagringen (LoRA:er eller pågående sekvenser). Teamet är underrättat: försök igen senare.
415	invalid_safetensors	Den uppladdade filen är inte en safetensors.
415	incompatible_lora	LoRA:n är för en annan arkitektur, angiven i architecture. Bilder kräver Krea 2, videor LTX 2.5 eller 2.3. Ingenting lagras och ingen kvot förbrukas.
413	lora_quota	Kontots LoRA-lagring är full (20 filer eller 10 GB). Svaret anger vad som är kvar; ta bort en fil för att frigöra utrymme.
413	image_too_large	Källbild eller mask överstiger 12 MB avkodat.
429	too_many_concurrent_renders, rate_limited, daily_cap	Ett tak är nått, se Retry-After.
429	daily_credit_cap	Nyckelns dagliga kredittak är nått (cap, spent, cost).
502	submission_failed, status_failed	En incident på rendersidan: försök igen om några sekunder.
503	license_check_failed	Kontot kan inte kontrolleras just nu: försök igen om en minut.
400	invalid_extend_frames	En förlängning vars extend_frames inte är 9, 17, 25, 33, 41 eller 49, eller ett extend_video som inte har exakt så många bildrutor.
400	extension_with_transition	En förlängning kan inte samtidigt vara en övergång, utom med consistency enhanced: ta bort end_image, eller begär förbättrad konsistens.
400	extension_too_short	length för en förlängning räknar bara de nya bildrutorna och måste vara minst 9.
404	clip_unavailable	Klippet som ska förlängas är inte längre tillgängligt: förläng det snabbare, eller skicka dess slut i extend_video. Som 502 misslyckades inläsningen: försök igen.
404	unknown_clip	Klippet som ska förlängas tillhör en annan licens.
404	unknown_sequence	Sekvensen finns inte, tillhör en annan licens eller har gått ut.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips utan job_id, eller export av en sekvens utan klipp.
409	not_exported_yet	GET /sequences/{id}/file innan exporten: anropa POST /sequences/{id}/export först.
404	unknown_export	Export av projektmappen: okänd rendering, från en annan licens eller inskickad för mer än 24 h sedan; ZIP-filen raderad (45 min efter första nedladdningen, högst 2 h).
409	export_in_progress	En export av projektmapp åt gången per licens.
413	export_too_large	Projektmapp över 2 GB: exportera tagningarna en och en.
400	unknown_reference	Export av projektmappen: en post i exclude_references anger ingen referens i exporten (varken id, namn eller @omnämnande).
400	invalid_export_options	Export av projektmappen: ett alternativ som inte är ett booleskt värde, en exclude_references som inte är en lista med texter, eller include_film utan include_media.
500	export_failed	Exporten misslyckades (orsak i detail): inget debiteras, försök igen.
422	resolution_mismatch, unreadable_clip	En render som lagts till manuellt (POST /sequences/{id}/clips) med en annan upplösning än sekvensens, eller oläsbar.
409	missing_shot	Ett klipp är inte klart ännu, eller inte längre tillgängligt (job_id anger vilket): vänta tills det är klart och exportera sedan igen.
409	sequence_exported	Sekvensen är redan hopsatt.
409	audio_mismatch	Ett klipp med ljud i en tyst sekvens, eller tvärtom.
413	extend_video_too_large	Klippets slut som du skickade överstiger 8 MB.
413	too_many_shots	Högst 30 klipp per sekvens.
422	unreadable_tail	Klippets slut, skickat eller inläst, är inte en läsbar video.
422	assembly_failed	Klippen har olika upplösningar, eller ljud på bara några av dem.
503	ultra_unavailable	Ultra-läget är stängt för tillfället: försök igen senare, eller rendera utan quality.
503	ultra_4k_unavailable	En 4K-storlek begärd i Ultra: 4K erbjuds inte längre, video går upp till 1080p (1920 x 1088).
400	ultra_incompatible	En övergång (end_image) begärd i Ultra.
400	extension_4k	Fortsättning av ett äldre 4K-klipp: 4K erbjuds inte längre, ett 4K-klipp kan inte förlängas (ultra_4k_unavailable med quality: "max"). Förläng ett klipp på högst 1080p.
400	resolution_above_quality	En storlek över 1080p (1920 x 1088) utan quality: "max": 1080p är taket i alla lägen.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Keyframes utanför tillåtet område: fler än 4, en ogiltig bild eller styrka; ett tillfälle utanför klippet, eller två keyframes med mindre än 0,5 s mellan; ett annat läge än Quality (Ultra, Multi-Ref), eller en förlängning utan consistency enhanced.
400	invalid_consistency, consistency_mode	consistency annat än standard eller enhanced; förbättrad konsistens begärd i Ultra eller i Multi-Ref.
400	consistency_explicit	En prompt som förbättrad konsistens inte renderar ännu, längre än 20 s (15 s med end_image), i en förlängning eller i en sekvens (ett enskilt kortare klipp renderas i standard-konsistens): korta ner det, eller använd standard.
403	consistency_licensed_only	Förbättrad konsistens är reserverad för licensinnehavare.
503	consistency_unavailable	Förbättrad konsistens är stängd för tillfället: försök igen senare, eller rendera i standard.
409	consistency_mismatch	Ett klipp vars consistency skiljer sig från sekvensens.
422	encoding_mismatch	En render som lagts till manuellt (POST /sequences/{id}/clips) vars consistency skiljer sig från de redan tillagda klippen.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	En bildhastighet (fps) som läget inte har (detail listar de som finns); förbättrad konsistens över 30 fps med automatisk varaktighet (sätt duration_auto till false och ange length); en förlängning med en annan bildhastighet än föregående klipp.
409	sequence_fps_mismatch	Ett klipp vars bildhastighet (fps) skiljer sig från sekvensens.
503	keyframes_unavailable	Keyframes är stängda för tillfället: rendera utan keyframes.
429	too_many_sequences	Högst 5 sekvenser pågående per licens: exportera en, eller vänta tills en går ut.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Ett karaktärsfält utanför tillåtet område (se Characters).
400	image_too_small	Ett foto under 1024 px på den långa sidan.
415	unsupported_image_format, unreadable_image	Ett foto eller en platsbild som inte är en läsbar JPEG, PNG eller WebP.
404	unknown_character	character_id finns inte på din licens, eller raderades (ett år utan användning, eller borttagen i appen).
409	character_limit	Karaktärstaket (max) är nått: ta bort en.
409	character_busy	Dess vyer håller på att skapas: vänta tills status inte längre är pending. Vid POST /characters: samma skapande håller på att sparas, skicka det igen några sekunder senare.
409	photo_view, empty_character, single_image_sheet	Vyn som kom från originalfotot kan inte göras om; eller karaktären har ingen läsbar vy (om det är lagringen som nekar läsningen: 503 storage_unavailable, försök igen); eller ett sheet som importerats som en enda bild (sparat som det är): dess vyer görs inte om och det klär inte ett nytt sheet (skicka vy 4 eller 1).
409	app_character	En instruction eller en uppladdad vy på en karaktär eller en character sheet från appen: reserverat för karaktärer och character sheets skapade via API:et.
400	instruction_too_long	En instruction längre än 200 tecken.
400	outfit_or_views_required	En character sheet tillagd utan outfit och utan views: ange en outfit att generera, eller vyer.
400	views_required	En character sheet tillagd med generate: false: ange minst en vy.
409	source_sheet_empty	En character sheet tillagd utan helbildsvy och utan byst, till en karaktär som inte har någon av dem att utgå från: skicka en av dem i views.
404	unknown_sheet	Bara en character sheet som lagts till via API:et (sheet_origin api) tas bort med DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	subject_id finns inte på din licens, eller raderades efter ett år utan användning.
409	subject_limit	Taket för subjekt (max) är nått: platser, objekt, djur, stilar och outfits räknas tillsammans; ta bort ett.
409	empty_subject	Ett objekt utan läsbar bild.
400	invalid_type, description_too_long, invalid_images	Ett objektfält utanför tillåtet område (se Platser, objekt, djur, stilar och outfits).
400	invalid_image	En objektbild som inte är en läsbar JPEG, PNG eller WebP på minst 512 px på den långa sidan (index anger vilken).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Generera ett subjekt: varken description, prompt eller startbild; en vynyckel som typen inte har (detail ger listan); count utanför 1 till 6, eller fler än 6 bilder, start inräknad; en prompt på över 2 000 tecken; instructions tomma, för långa eller för flera vyer.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	En serie körs redan på det här subjektet; ett subjekt skapat från bilder (lägg till bilder via /images); en vy som redan är gjord (gör om den); en start som ska göras om medan vyer utgår från den; en misslyckad start som först måste göras om; en importerad start, som inte kan göras om.
404 / 503	unknown_view, generation_unavailable	En vy som aldrig begärts (lägg till den); generering av subjekt är inte tillgänglig på servern för tillfället: försök igen senare.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref utanför tillåtet område: 1 till 4 karaktärer (12 i Ultra), ingen förlängning eller övergång, formaten och längderna för Multi-Ref Video.
400	duplicate_name, invalid_strength, unknown_mention	Två karaktärer med samma namn; strength utanför 0 till 2; ett @Namn i prompten utan karaktär (mentions listar dem).
400	voice_requires_audio, voice_slot	En karaktärsröst (voice_b64) utan ljud ("audio": true); eller på en annan karaktär än characters[0] och characters[1] (motorn stöder 2 röster). index anger vilken.
400	invalid_voice_choice	voice annat än character eller original i en Face swap, eller characters[].voice annat än character eller generated i Multi-Ref Video.
413	audio_too_large	En karaktärsröst över 4 MB, eller över 2 MB i en Face swap. Bara de första 5 sekunderna används (20 i en Face swap): skicka ett kort utdrag.
415	unsupported_audio_format	En karaktärsröst som inte är en läsbar ljudfil (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Fler än 4 karaktärer, objekt och djur totalt, utanför Ultra; ett subjekt i fel fält (en plats i subjects, ett objekt som location, en stil utanför styles, en outfit utanför outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Create an image: count 1 eller 2, view 1 till 5 och närvarande i character sheet, lora_pass 0,3 till 0,9, ett subjekts image bland dess bilder, bredd och höjd från 256 till 2048.
400	character_not_ready	Create an image: den valda vyn för en karaktär har ingen bild än.
503	multiref_image_disabled	Create an image är inte öppet på den här servern än.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Stilar, outfits eller rörelse utanför Multi-Ref i Ultra; fler än 30 bilder i Ultra; ett worn_by som inte namnger någon karaktär.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion utan motion_id och utan video_b64; ett annat mode än camera eller choreography; en oläslig video, eller en utanför 4 till 30 s (input_video_out_of_limits); ett motion_id som aldrig laddats upp (ingen PUT).
404 / 409	unknown_motion, motion_already_used	Ett motion_id som är okänt, redan använt eller äldre än 2 timmar: ladda upp videon igen.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	En rörelsevideo över 20 MB (20 MB när den skalats ner till 480p); rörelsen är inte öppen än (ultra.motion_per_second är null); ett mode som inte är öppet än.
409	extension_link_expired	Ett extend_job_id som din licens inte känner till, eller en Ultra-tagning äldre än 24 timmar: ladda upp originalet (POST /extensions) och skicka extend_upload_id.
400	extension_real_face	Videon som ska förlängas i Ultra renderades inte i Ultra-läget (till exempel en rendering från ett annat läge) och visar ett realistiskt ansikte: inget debiteras. Förläng den i kvalitetsläge, eller gör om tagningen i Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Ultra-förlängning utanför gränserna: extend_upload_id eller backward utan quality: "max" (eller från ett klipp som inte är Ultra); en startbild, referenser, rörelse eller förbättrad konsistens samtidigt; en annan riktning än forward eller backward; backward i en sekvens; extend_video i Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	En uppladdad video över 1080p; en oläslig MP4, eller en utanför 4 till 30 s (input_video_out_of_limits); en fil som aldrig laddats upp (ingen PUT).
400	input_video_out_of_limits	En video som skickas till Ultra-läget (rörelse, video att förlänga) utanför sina gränser, kontrollerade före renderingen, inget dras: limit anger vilken (duration: 4 till 30 s; total_duration: 30 s med referensljuden; count: 10; size: 200 MB; format: MP4 eller MOV; fps: 24 till 60; pixels: bredd × höjd från 409 600 till 8 295 044; aspect_ratio: 0,4 till 2,5), med value, min och max.
404 / 409	unknown_extension_upload, extension_upload_used	Ett extend_upload_id som är okänt, äldre än 2 timmar eller redan använt: ladda upp filen igen.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	En fil över 60 MB; Ultra-förlängningen är inte öppen än (ultra.extend_per_second är null); bakåt är inte öppet än.
413	references_too_large	De förberedda vyerna överstiger renderns budget: färre karaktärer, eller ett mindre format.
400	video_required, character_required	En Face swap utan video_b64, eller utan character_id.
413	video_too_large	En Face swap-video över 20 MB: klipp eller komprimera den först, eller använd MCP-verktyget tendre_face_swap, som accepterar upp till 95 MB.
415	unreadable_video	Face swap-videon är inte en läsbar MP4, MOV, WebM eller MKV.
400	invalid_start, invalid_duration, passage_too_short	Ett Face swap-avsnitt utanför tillåtet område: start under 0 eller efter videons slut; duration utanför 0,5 till 20 s; ett avsnitt kortare än en halv sekund.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Ett Face swap-fält utanför tillåtet område: zone annat än tight, normal eller wide; part annat än full eller head; likeness utanför 0,5 till 2; scene över 400 tecken; description över 360; name över 60.
413	face_swap_too_large	Avsnittet är fortfarande för tungt efter förberedelse: ange en kortare duration.
429	server_busy	Vår server förbereder redan två Face swap-videor: försök igen efter Retry-After (20 s). MCP-uppladdningslänken svarar med samma kod som 503 när för många filer väntar: försök igen om några minuter.
503	face_swap_unavailable, face_swap_price_missing	Face swap är stängt, eller saknar pris, för tillfället: försök igen senare.
503	creation_unavailable, multiref_unavailable, storage_unavailable	Tjänsten är otillgänglig för tillfället: försök igen senare.
500	internal_error	En oväntad incident på serversidan: försök igen, och berätta för oss om det händer igen.

Ultra per sekund (Ultra):

Kod	error	Vad det betyder och vad du gör
400	resolution_outside_ultra	Över 1080p: 480p, 720p eller 1080p.
400	engine_refused	Motorn nekar texten eller en bild: orsaken står i detail och koden i code. Inget debiteras: formulera om.
502	engine_unavailable	Motorn svarar inte: försök igen om några minuter. Inget debiteras.
409	render_in_progress	Avbrott av en rendering som redan beräknas: den stannar inte längre, den levereras och debiteras.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref i Ultra: en referensbild är oläsbar eller för tung (högst 20 MB totalt), eller ett alternativ stöds inte.
403	multiref_ultra_unavailable	Multi-Ref i Ultra per sekund är ännu inte öppet för det här kontot.

Felnamnen är de exakta strängar som API:et returnerar. Matcha på dem snarare än på meddelandet, som kan formuleras om.

Ett svar är inget fel: en Multi-Ref-render eller en Face swap med en karaktär som bara har en vy går igenom, med en limited_likeness-varning i warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). Likheten är begränsad: skapa karaktärens sju vyer för en trovärdig likhet.

En Multi-Ref-render i Ultra med 9 till 12 karaktärer går också igenom, med en many_characters-varning: några kan saknas eller blandas ihop (8 rekommenderas).

God praxis

• Poll var 3:e sekund, inte snabbare. Kön är delad, och att bombardera den hjälper ingen.
• Ladda ner så snart statusen är completed. Filen arkiveras inte.
• Skriv prompts på engelska, och för videor beskriv rörelsen snarare än stillbilden.
• En nyckel per användningsområde, och ett dagligt kredittak på varje nyckel som lever på en server. En läckt nyckel med ett tak kostar dig en dag, inte hela saldot.
• Behandla en 429 som normalt, inte som ett fel: vänta på Retry-After och fortsätt.
• En anslutning som bryts före svaret kostar ingenting. Om en inskickad bild eller video blir utan svar (en proxys tidsgräns överskriden, fel 524, programmet stoppat) startas renderingen inte, eller avbryts direkt, och inget debiteras: skicka bara förfrågan igen. För en serie bilder (count) avbryts även de renderingar som redan skapats. Att skapa en karaktär fortsätter däremot: skickar du samma förfrågan igen får du tillbaka samma karaktär, utan att något debiteras två gånger (se Characters).

Prompter loggas på vår sida, precis som för appen, av säkerhetsskäl.