API Pro: limites, códigos de erro e boas práticas

Limites

Cada chave tem três: renders simultâneos (2 por defeito), submissões por minuto (60 por defeito) e, se definires um, um limite diário de créditos.

Ao ultrapassar um limite, a resposta é 429 com um cabeçalho Retry-After em segundos. Uma chamada recusada não tem custo. O dia usado para os limites é o dia UTC.

Os vídeos longos acrescentam dois limites próprios: 30 shots por sequência e 5 sequências em curso por licença (ver Vídeos).

As personagens têm um: 50 por licença Pro, incluindo as criadas na app, e uma personagem sem uso durante um ano é eliminada (ver Personagens). Locais, objetos e animais têm o seu próprio limite, contado separadamente: 50 por licença Pro (10 com uma licença pessoal, na app), eliminados após o mesmo ano sem uso (ver Lugares, objetos, animais, estilos e roupas).

O Face swap tem dois limites próprios: uma passagem de no máximo 20 s por render, e o nosso servidor prepara dois vídeos de cada vez. Ao ultrapassar este limite, a resposta é 429 server_busy: tenta novamente após Retry-After (ver Face swap). Pelo MCP, um Face swap com transição aceita um vídeo inteiro de no máximo 60 s, e o servidor trata dois ao mesmo tempo: acima disso, a ferramenta pede para tentar de novo dentro de alguns minutos.

O nosso cartão é partilhado com os utilizadores da app. Quando está ocupado, os teus renders vão para GPUs alugadas, ao mesmo preço e através da mesma API, com mais algumas dezenas de segundos no arranque.

Códigos de erro

Código	error	O que significa e o que fazer
400	prompt_required	Adiciona um prompt.
400	forbidden_content	O filtro de conteúdo recusou o prompt.
400	invalid_seed	seed deve ser um número inteiro de 0 a 4294967295.
400	image_required, inpaint_images_required	O modo precisa de image_b64, e de mask_b64 para inpaint.
401	key_required, invalid_key	Cabeçalho em falta, ou chave desconhecida.
402	insufficient_credits	Saldo insuficiente para este render (cost é indicado). A resposta inclui buy_url, a página de compra de créditos da tua licença. Um render ou um treino em curso reserva o seu preço até terminar: engaged indica quantos créditos estão assim reservados.
402	confirmation_required, payment_declined	Uma compra com o teu cartão guardado (POST /credits/purchase): o teu banco pede a tua confirmação ou recusou o pagamento. Usa buy_url, o link de compra normal.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Uma compra com o teu cartão guardado: o teu agente não está autorizado a comprar (carregamento automático da tua página de conta), não há nenhum cartão guardado ou a compra ultrapassaria o teu limite mensal. Usa buy_url.
409	topup_in_progress, purchase_in_progress	Está em curso outro pagamento com o teu cartão guardado: espera que termine.
400	unknown_pack	Uma compra com um pack desconhecido, ou uma quantidade livre fora dos limites ou que não é um escalão inteiro.
503	payment_unavailable	Não foi possível confirmar o pagamento: não sabemos se o débito foi feito. Não tentes de novo de imediato; um débito feito é creditado.
403	key_disabled, key_revoked, key_expired	Chave desativada, revogada ou expirada: cria uma nova na app.
403	license_revoked, license_not_pro	Licença revogada, ou conta que não é Pro.
403	missing_scope	A chave não tem a permissão pedida, indicada em scope.
403	unknown_lora	Uma personagem que não pertence à conta.
404	media_unavailable	O ficheiro foi eliminado: submete novamente.
404	unknown_lora	Em DELETE /loras/{name}, nenhum ficheiro com esse nome na conta. Nota o código: o mesmo nome responde 403 quando um render pede uma personagem que não é tua.
411	size_required	Um upload de LoRA sem Content-Length. O corpo é bruto, por isso o tamanho tem de ser anunciado.
413	file_too_large	Um LoRA acima de 800 MB, ou acima de 90 MB num único upload. Envia-o em partes. Um 413 simples sem corpo JSON é outra coisa: o pedido nunca chegou à API, ver a secção de upload.
413	part_too_large	Uma parte maior do que o max_part_size anunciado pela sessão.
404	unknown_upload_session	O uploadId não existe, ou a sessão foi abandonada (seis horas) ou cancelada por uma parte rejeitada.
503	upload_refused, part_refused	O armazenamento não estava acessível durante o upload: tenta novamente.
507	storage_full	Sem espaço no armazenamento do servidor (LoRAs ou sequências em curso). A equipa foi alertada: tenta mais tarde.
415	invalid_safetensors	O ficheiro enviado não é um safetensors.
415	incompatible_lora	O LoRA é para outra arquitetura, indicada em architecture. As imagens usam apenas Krea 2, os vídeos LTX 2.5 ou 2.3. Nada é armazenado e nenhuma quota é gasta.
413	lora_quota	O armazenamento de LoRA da conta está cheio (20 ficheiros ou 10 GB). A resposta indica o que resta; elimina um ficheiro para libertar espaço.
413	image_too_large	Imagem de origem ou máscara acima de 12 MB descodificados.
429	too_many_concurrent_renders, rate_limited, daily_cap	Um limite foi atingido, ver Retry-After.
429	daily_credit_cap	O limite diário de créditos da chave foi atingido (cap, spent, cost).
502	submission_failed, status_failed	Um incidente no lado do render: tenta novamente em alguns segundos.
503	license_check_failed	A conta não pode ser verificada de momento: tenta novamente em um minuto.
400	invalid_extend_frames	Uma extensão cujo extend_frames não é 9, 17, 25, 33, 41 ou 49, ou um extend_video que não tem exatamente esse número de frames.
400	extension_with_transition	Uma extensão não pode ser também uma transição, exceto com consistency enhanced: remove end_image, ou pede coerência reforçada.
400	extension_too_short	O length de uma extensão conta apenas os novos frames e deve ser no mínimo 9.
404	clip_unavailable	O clip a estender já não está disponível: estende-o mais cedo, ou envia o seu final em extend_video. Como 502, a leitura falhou: tenta novamente.
404	unknown_clip	O clip a estender pertence a outra licença.
404	unknown_sequence	A sequência não existe, pertence a outra licença, ou expirou.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips sem job_id, ou a exportação de uma sequência sem nenhum shot.
409	not_exported_yet	GET /sequences/{id}/file antes da exportação: chama primeiro POST /sequences/{id}/export.
404	unknown_export	Exportação da pasta de projeto: render desconhecido, de outra licença ou enviado há mais de 24 h; ZIP apagado (45 min após o primeiro download, 2 h no máximo).
409	export_in_progress	Uma exportação de pasta de projeto de cada vez por licença.
413	export_too_large	Pasta de projeto com mais de 2 GB: exporta os planos um a um.
400	unknown_reference	Exportação da pasta de projeto: uma entrada de exclude_references não designa nenhuma referência da exportação (nem id, nem nome, nem @menção).
400	invalid_export_options	Exportação da pasta de projeto: uma opção que não é booleana, um exclude_references que não é uma lista de textos, ou include_film sem include_media.
500	export_failed	A exportação falhou (motivo em detail): nada é cobrado, tenta de novo.
422	resolution_mismatch, unreadable_clip	Um render adicionado manualmente (POST /sequences/{id}/clips) com resolução diferente da sequência, ou ilegível.
409	missing_shot	Um shot ainda não terminou, ou já não está disponível (job_id identifica-o): aguarda que termine e exporta novamente.
409	sequence_exported	A sequência já foi montada.
409	audio_mismatch	Um shot com som numa sequência silenciosa, ou o inverso.
413	extend_video_too_large	O final do clip que enviaste ultrapassa 8 MB.
413	too_many_shots	No máximo 30 shots por sequência.
422	unreadable_tail	O final do clip, enviado ou lido, não é um vídeo legível.
422	assembly_failed	Os shots têm resoluções diferentes, ou som apenas em alguns deles.
503	ultra_unavailable	O modo Ultra está temporariamente indisponível: tenta mais tarde, ou renderiza sem quality.
503	ultra_4k_unavailable	Um tamanho 4K pedido em Ultra: o 4K deixou de ser oferecido, o vídeo vai até 1080p (1920 x 1088).
400	ultra_incompatible	Uma transição (end_image) pedida em Ultra.
400	extension_4k	A continuação de um clip 4K anterior: o 4K deixou de ser oferecido, um clip 4K já não pode ser prolongado (ultra_4k_unavailable com quality: "max"). Prolonga um clip de 1080p no máximo.
400	resolution_above_quality	Um tamanho acima de 1080p (1920 x 1088) sem quality: "max": 1080p é o máximo em todos os modos.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Imagens-chave fora dos limites: mais de 4, uma imagem ou Força inválida; um momento fora do clip, ou duas imagens-chave com menos de 0,5 s de intervalo; um modo diferente de Qualidade (Ultra, Multi-Ref), ou uma extensão sem consistency enhanced.
400	invalid_consistency, consistency_mode	consistency diferente de standard ou enhanced; coerência reforçada pedida em Ultra ou em Multi-Ref.
400	consistency_explicit	Um prompt que a coerência reforçada ainda não renderiza, acima de 20 s (15 s com end_image), numa extensão ou numa sequência (um único shot mais curto renderiza em coerência padrão): encurta-o, ou usa standard.
403	consistency_licensed_only	A coerência reforçada está reservada para licenças.
503	consistency_unavailable	A coerência reforçada está temporariamente indisponível: tenta mais tarde, ou renderiza em standard.
409	consistency_mismatch	Um shot cuja consistency difere da sequência.
422	encoding_mismatch	Um render adicionado manualmente (POST /sequences/{id}/clips) cuja consistency difere dos shots já adicionados.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	Uma taxa de quadros (fps) que o modo não suporta (detail lista as disponíveis); coerência reforçada acima de 30 fps com duração automática (define duration_auto como false e indica length); uma extensão com taxa de quadros diferente do clip anterior.
409	sequence_fps_mismatch	Um shot cuja taxa de quadros (fps) difere da sequência.
503	keyframes_unavailable	As imagens-chave estão temporariamente indisponíveis: renderiza sem keyframes.
429	too_many_sequences	No máximo 5 sequências em curso por licença: exporta uma, ou aguarda que uma expire.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Um campo de personagem fora dos limites (ver Personagens).
400	image_too_small	Uma fotografia com menos de 1024 px no lado maior.
415	unsupported_image_format, unreadable_image	Uma fotografia ou imagem de local que não é um JPEG, PNG ou WebP legível.
404	unknown_character	O character_id não está na tua licença, ou foi eliminado (um ano sem uso, ou apagado na app).
409	character_limit	O limite de personagens (max) foi atingido: elimina uma.
409	character_busy	As suas vistas estão a ser geradas: aguarda até que status deixe de ser pending. Em POST /characters: a mesma criação está a ser registada, volta a enviá-la alguns segundos depois.
409	photo_view, empty_character, single_image_sheet	A vista proveniente da fotografia original não pode ser refeita; ou a personagem não tem nenhuma vista legível (se for o armazenamento a recusar a leitura: 503 storage_unavailable, tente novamente); ou uma sheet importada como uma única imagem (mantida tal como está): as suas vistas não se refazem e não veste uma nova sheet (envie a vista 4 ou 1).
409	app_character	Uma instruction ou uma vista enviada numa personagem ou numa character sheet feitas na app: reservado para personagens e character sheets criadas através da API.
400	instruction_too_long	Uma instruction com mais de 200 caracteres.
400	outfit_or_views_required	Uma character sheet adicionada sem outfit nem views: dá uma roupa para gerar, ou vistas.
400	views_required	Uma character sheet adicionada com generate: false: dá pelo menos uma vista.
409	source_sheet_empty	Uma character sheet adicionada sem vista de corpo inteiro nem busto, a uma personagem que não tem nenhum dos dois de onde partir: envia um deles em views.
404	unknown_sheet	Só uma character sheet adicionada através da API (sheet_origin api) se apaga com DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	O subject_id não está na tua licença, ou foi eliminado após um ano sem uso.
409	subject_limit	O limite de sujeitos (max) foi atingido: locais, objetos, animais, estilos e roupas contam em conjunto; elimina um.
409	empty_subject	Um sujeito sem nenhuma imagem legível.
400	invalid_type, description_too_long, invalid_images	Um campo de sujeito fora dos limites (ver Lugares, objetos, animais, estilos e roupas).
400	invalid_image	Uma imagem de sujeito que não é um JPEG, PNG ou WebP legível com pelo menos 512 px no lado maior (index indica qual).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Gerar um sujeito: nem description, nem prompt, nem imagem de partida; uma chave de vista que o tipo não tem (detail dá a lista); count fora de 1 a 6, ou mais de 6 imagens, partida incluída; um prompt com mais de 2000 caracteres; instructions vazias, demasiado longas ou para várias vistas.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	Já há uma série em curso neste sujeito; um sujeito criado com imagens (adiciona imagens por /images); uma vista já feita (refá-la); uma partida a refazer quando já partem vistas dela; uma partida falhada a refazer primeiro; uma partida importada, que não se refaz.
404 / 503	unknown_view, generation_unavailable	Uma vista nunca pedida (adiciona-a); a geração de sujeitos não está disponível no servidor de momento: tenta mais tarde.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref fora dos limites: 1 a 4 personagens (12 em Ultra), sem extensão ou transição, os formatos e durações de Multi-Ref Vídeo.
400	duplicate_name, invalid_strength, unknown_mention	Duas personagens com o mesmo nome; strength fora de 0 a 2; um @Nome no prompt sem personagem correspondente (mentions lista-os).
400	voice_requires_audio, voice_slot	Uma voz de personagem (voice_b64) sem som ("audio": true); ou numa personagem diferente de characters[0] e characters[1] (o motor suporta 2 vozes). index indica qual.
400	invalid_voice_choice	voice diferente de character ou original num Face swap, ou characters[].voice diferente de character ou generated no Multi-Ref Vídeo.
413	audio_too_large	Uma voz de personagem acima de 4 MB, ou acima de 2 MB num Face swap. Apenas os primeiros 5 segundos são usados (20 num Face swap): envia um excerto curto.
415	unsupported_audio_format	Uma voz de personagem que não é um ficheiro de áudio legível (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Mais de 4 personagens, objetos e animais no total, fora do Ultra; um sujeito no campo errado (um local em subjects, um objeto como location, um estilo fora de styles, uma roupa fora de outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Criar uma imagem: count 1 ou 2, view de 1 a 5 e presente na sheet, lora_pass de 0,3 a 0,9, a image de um sujeito entre as suas imagens, largura e altura de 256 a 2048.
400	character_not_ready	Criar uma imagem: a vista escolhida de uma personagem ainda não tem imagem.
503	multiref_image_disabled	Criar uma imagem ainda não está aberto neste servidor.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Estilos, roupas ou movimento fora do Multi-Ref em Ultra; mais de 30 imagens em Ultra; um worn_by que não nomeia nenhuma personagem.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion sem motion_id nem video_b64; um mode diferente de camera ou choreography; um vídeo ilegível, ou fora de 4 a 30 s (input_video_out_of_limits); um motion_id nunca enviado (sem PUT).
404 / 409	unknown_motion, motion_already_used	Um motion_id desconhecido, já usado ou com mais de 2 horas: envia o vídeo de novo.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	Um vídeo de movimento com mais de 20 MB (20 MB depois de reduzido a 480p); o movimento ainda não está aberto (ultra.motion_per_second vale null); um mode ainda não aberto.
409	extension_link_expired	Um extend_job_id que a tua licença não conhece, ou um plano Ultra com mais de 24 horas: envia o seu original (POST /extensions) e passa extend_upload_id.
400	extension_real_face	O vídeo a prolongar em Ultra não foi renderizado no modo Ultra (o render de outro modo, por exemplo) e mostra um rosto realista: nada é debitado. Prolonga-o no modo Qualidade, ou refaz o plano em Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Extensão Ultra fora dos limites: extend_upload_id ou backward sem quality: "max" (ou a partir de um clip que não é Ultra); uma imagem inicial, referências, movimento ou coerência reforçada com ela; uma direção diferente de forward ou backward; backward numa sequência; extend_video em Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	Um vídeo enviado acima de 1080p; um MP4 ilegível, ou fora de 4 a 30 s (input_video_out_of_limits); um ficheiro nunca enviado (sem PUT).
400	input_video_out_of_limits	Um vídeo enviado ao modo Ultra (movimento, vídeo a prolongar) fora dos seus limites, verificados antes da renderização, nada debitado: limit diz qual (duration: 4 a 30 s; total_duration: 30 s com os sons de referência; count: 10; size: 200 MB; format: MP4 ou MOV; fps: 24 a 60; pixels: largura × altura de 409 600 a 8 295 044; aspect_ratio: 0,4 a 2,5), com value, min e max.
404 / 409	unknown_extension_upload, extension_upload_used	Um extend_upload_id desconhecido, com mais de 2 horas ou já usado: envia o ficheiro de novo.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	Um ficheiro com mais de 60 MB; a extensão Ultra ainda não está aberta (ultra.extend_per_second vale null); para trás ainda não está aberta.
413	references_too_large	As vistas preparadas ultrapassam o orçamento do render: menos personagens, ou um formato mais pequeno.
400	video_required, character_required	Um Face swap sem video_b64, ou sem character_id.
413	video_too_large	Um vídeo de Face swap acima de 20 MB: corta-o ou comprime-o primeiro, ou usa a ferramenta MCP tendre_face_swap, que aceita até 95 MB.
415	unreadable_video	O vídeo de Face swap não é um MP4, MOV, WebM ou MKV legível.
400	invalid_start, invalid_duration, passage_too_short	Uma passagem de Face swap fora dos limites: start abaixo de 0 ou além do fim do vídeo; duration fora de 0,5 a 20 s; uma passagem mais curta do que meio segundo.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Um campo de Face swap fora dos limites: zone diferente de tight, normal ou wide; part diferente de full ou head; likeness fora de 0,5 a 2; scene com mais de 400 caracteres; description com mais de 360; name com mais de 60.
413	face_swap_too_large	A passagem continua demasiado pesada após a preparação: indica uma duration mais curta.
429	server_busy	O nosso servidor já está a preparar dois vídeos de Face swap: tenta novamente após Retry-After (20 s). O link de upload MCP responde com o mesmo código como 503 quando há demasiados ficheiros em espera: tenta novamente em alguns minutos.
503	face_swap_unavailable, face_swap_price_missing	O Face swap está indisponível, ou sem preço, de momento: tenta mais tarde.
503	creation_unavailable, multiref_unavailable, storage_unavailable	O serviço está temporariamente indisponível: tenta mais tarde.
500	internal_error	Um incidente inesperado do lado do servidor: tenta novamente, e diz-nos se acontecer outra vez.

Ultra faturado ao segundo (Ultra):

Código	error	O que significa e o que fazer
400	resolution_outside_ultra	Acima de 1080p: 480p, 720p ou 1080p.
400	engine_refused	O motor recusa o texto ou uma imagem: o motivo está em detail e o código em code. Nada é debitado: reformula.
502	engine_unavailable	O motor não responde: tenta de novo dentro de alguns minutos. Nada é debitado.
409	render_in_progress	Cancelamento de uma renderização já em cálculo: já não para, é entregue e faturada.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref em Ultra: uma imagem de referência está ilegível ou é demasiado pesada (20 MB no máximo no total), ou uma opção não é suportada.
403	multiref_ultra_unavailable	O Multi-Ref em Ultra faturado ao segundo ainda não está aberto a esta conta.

Os nomes dos erros são as strings exatas que a API devolve. Faz a correspondência por eles e não pela mensagem, que pode ser reformulada.

Uma resposta não é um erro: um render Multi-Ref ou um Face swap com uma personagem que tem apenas uma vista é processado, com um aviso limited_likeness em warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). A semelhança é limitada: cria as sete vistas da personagem para uma semelhança fiel.

Um render Multi-Ref em Ultra com 9 a 12 personagens também é processado, com um aviso many_characters: algumas podem faltar ou misturar-se (recomendam-se 8).

Boas práticas

• Faz polling a cada 3 segundos, não mais frequentemente. A fila é partilhada, e bombardeá-la não ajuda ninguém.
• Faz o download assim que o estado for completed. O ficheiro não é arquivado.
• Escreve os prompts em inglês, e para vídeos descreve o movimento em vez da imagem estática.
• Uma chave por uso, e um limite diário de créditos em cada chave que vive num servidor. Uma chave comprometida com um limite custa-te um dia, não o saldo todo.
• Trata um 429 como algo normal, não como uma falha: aguarda Retry-After e continua.
• Uma ligação cortada antes da resposta não custa nada. Se um envio de imagem ou vídeo ficar sem resposta (tempo limite de um proxy excedido, erro 524, programa parado), o render não é iniciado, ou é cancelado de imediato, e nada é cobrado: basta voltar a enviar o pedido. Num lote de imagens (count), os renders já criados também são cancelados. A criação de uma personagem, essa, continua: reenviar o mesmo pedido devolve a mesma personagem, sem cobrar nada duas vezes (ver Personagens).

Os prompts são registados do nosso lado, tal como na app, por razões de segurança.