API Pro: límites, códigos de error y buenas prácticas

Límites

Cada clave lleva tres: renders simultáneos (2 por defecto), envíos por minuto (60 por defecto) y, si lo configuras, un límite diario de créditos.

Al superar un límite, la respuesta es 429 con un encabezado Retry-After en segundos. Una llamada rechazada no cuesta nada. El día utilizado para los límites es el día UTC.

Los vídeos largos añaden dos límites propios: 30 planos por secuencia y 5 secuencias en curso por licencia (ver Vídeos).

Los personajes tienen uno: 50 por licencia Pro, incluidos los creados en la app, y un personaje sin usar durante un año se elimina (ver Personajes). Los decorados, objetos y animales tienen el suyo, contado por separado: 50 por licencia Pro (10 con una licencia personal, en la app), eliminados tras el mismo año sin uso (ver Lugares, objetos, animales, estilos y outfits).

El Face swap tiene dos propios: un pasaje de 20 s como máximo por render, y nuestro servidor prepara dos vídeos a la vez. Al superarlos, la respuesta es 429 server_busy: reintenta después de Retry-After (ver Face swap). Por el MCP, un Face swap con transición admite un vídeo entero de 60 s como máximo, y el servidor procesa dos a la vez: por encima, la herramienta pide volver a intentarlo en unos minutos.

Nuestra propia tarjeta es compartida con los usuarios de la app. Cuando está ocupada, tus renders van a GPUs alquiladas, al mismo precio y a través de la misma API, con unos decenas de segundos más al arrancar.

Códigos de error

Código	error	Qué significa y qué hacer
400	prompt_required	Añade un prompt.
400	forbidden_content	El filtro de contenido rechazó el prompt.
400	invalid_seed	seed debe ser un número entero de 0 a 4294967295.
400	image_required, inpaint_images_required	El modo necesita image_b64, y mask_b64 para inpaint.
401	key_required, invalid_key	Encabezado ausente, o clave desconocida.
402	insufficient_credits	Saldo insuficiente para este render (se indica cost). La respuesta incluye buy_url, la página de compra de créditos de tu licencia. Un render o un entrenamiento en curso reserva su precio hasta que termina: engaged indica cuántos créditos están retenidos de ese modo.
402	confirmation_required, payment_declined	Una compra con tu tarjeta guardada (POST /credits/purchase): tu banco pide tu confirmación o ha rechazado el pago. Usa buy_url, el enlace de compra normal.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Una compra con tu tarjeta guardada: tu agente no está autorizado a comprar (recarga automática de tu página de cuenta), no hay ninguna tarjeta guardada o la compra superaría tu límite mensual. Usa buy_url.
409	topup_in_progress, purchase_in_progress	Hay otro pago en curso con tu tarjeta guardada: espera a que termine.
400	unknown_pack	Una compra con un pack desconocido, o una cantidad libre fuera de los límites o que no es un tramo entero.
503	payment_unavailable	No se ha podido confirmar el pago: no sabemos si el cargo se ha realizado. No vuelvas a intentarlo enseguida; un cargo realizado se acredita.
403	key_disabled, key_revoked, key_expired	Clave desactivada, revocada o expirada: crea una nueva en la app.
403	license_revoked, license_not_pro	Licencia revocada, o una cuenta que no es Pro.
403	missing_scope	A la clave le falta el permiso solicitado, indicado en scope.
403	unknown_lora	Un personaje que no pertenece a la cuenta.
404	media_unavailable	El archivo ya no existe: envíalo de nuevo.
404	unknown_lora	En DELETE /loras/{name}, ningún archivo con ese nombre en la cuenta. Nota el código: el mismo nombre devuelve 403 cuando un render solicita un personaje que no es tuyo.
411	size_required	Una subida de LoRA sin Content-Length. El cuerpo es raw, así que hay que anunciar el tamaño.
413	file_too_large	Un LoRA de más de 800 MB, o más de 90 MB en una sola subida. Envíalo en partes. Un 413 sin cuerpo JSON es otra cosa: la petición nunca llegó a la API, consulta la sección de subida.
413	part_too_large	Una parte es mayor que el max_part_size anunciado por la sesión.
404	unknown_upload_session	El uploadId no existe, o la sesión fue abandonada (seis horas) o cancelada por una parte rechazada.
503	upload_refused, part_refused	No se pudo acceder al almacenamiento durante la subida: reintenta.
507	storage_full	No queda espacio en el almacenamiento del servidor (LoRAs o secuencias en curso). El equipo ha sido alertado: reintenta más tarde.
415	invalid_safetensors	El archivo subido no es un safetensors.
415	incompatible_lora	El LoRA es para otra arquitectura, indicada en architecture. Las imágenes solo admiten Krea 2; los vídeos, LTX 2.5 o 2.3. No se guarda nada y no se consume ninguna cuota.
413	lora_quota	El almacenamiento de LoRAs de la cuenta está lleno (20 archivos o 10 GB). La respuesta indica lo que queda; elimina un archivo para hacer sitio.
413	image_too_large	Imagen fuente o máscara de más de 12 MB decodificada.
429	too_many_concurrent_renders, rate_limited, daily_cap	Se ha alcanzado un límite, consulta Retry-After.
429	daily_credit_cap	Se ha alcanzado el límite diario de créditos de la clave (cap, spent, cost).
502	submission_failed, status_failed	Un incidente en el lado del render: reintenta en unos segundos.
503	license_check_failed	La cuenta no se puede verificar ahora mismo: reintenta en un minuto.
400	invalid_extend_frames	Una extensión cuyo extend_frames no es 9, 17, 25, 33, 41 o 49, o un extend_video que no tiene exactamente ese número de fotogramas.
400	extension_with_transition	Una extensión no puede ser también una transición, salvo con consistency enhanced: elimina end_image, o solicita coherencia reforzada.
400	extension_too_short	El length de una extensión cuenta solo los nuevos fotogramas y debe ser al menos 9.
404	clip_unavailable	El clip a extender ya no está disponible: extiéndelo antes, o envía su final en extend_video. Como 502, falló la lectura: reintenta.
404	unknown_clip	El clip a extender pertenece a otra licencia.
404	unknown_sequence	La secuencia no existe, pertenece a otra licencia o ha expirado.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips sin job_id, o la exportación de una secuencia sin ningún plano.
409	not_exported_yet	GET /sequences/{id}/file antes de la exportación: llama primero a POST /sequences/{id}/export.
404	unknown_export	Exportación de la carpeta de proyecto: render desconocido, de otra licencia o enviado hace más de 24 h; ZIP borrado (45 min después de la primera descarga, 2 h como máximo).
409	export_in_progress	Una exportación de carpeta de proyecto a la vez por licencia.
413	export_too_large	Carpeta de proyecto de más de 2 GB: exporta los planos uno a uno.
400	unknown_reference	Exportación de la carpeta de proyecto: una entrada de exclude_references no designa ninguna referencia de la exportación (ni id, ni nombre, ni @mención).
400	invalid_export_options	Exportación de la carpeta de proyecto: una opción que no es booleana, un exclude_references que no es una lista de textos, o include_film sin include_media.
500	export_failed	La exportación ha fallado (motivo en detail): no se cobra nada, vuelve a intentarlo.
422	resolution_mismatch, unreadable_clip	Un render añadido manualmente (POST /sequences/{id}/clips) con una resolución distinta a la de la secuencia, o ilegible.
409	missing_shot	Un plano aún no ha terminado o ya no está disponible (job_id lo identifica): espera a que termine y exporta de nuevo.
409	sequence_exported	La secuencia ya está ensamblada.
409	audio_mismatch	Un plano con sonido en una secuencia silenciosa, o al revés.
413	extend_video_too_large	El final de clip que enviaste supera los 8 MB.
413	too_many_shots	Máximo 30 planos por secuencia.
422	unreadable_tail	El final del clip, enviado o leído, no es un vídeo legible.
422	assembly_failed	Los planos tienen resoluciones distintas, o solo algunos tienen sonido.
503	ultra_unavailable	El modo Ultra está cerrado por el momento: reintenta más tarde, o genera sin quality.
503	ultra_4k_unavailable	Un tamaño 4K pedido en Ultra: el 4K ya no se ofrece, el vídeo llega hasta 1080p (1920 x 1088).
400	ultra_incompatible	Se solicitó una transición (end_image) en Ultra.
400	extension_4k	La continuación de un clip 4K anterior: el 4K ya no se ofrece, un clip 4K no se puede prolongar (ultra_4k_unavailable con quality: "max"). Prolonga un clip de 1080p como máximo.
400	resolution_above_quality	Un tamaño superior a 1080p (1920 x 1088) sin quality: "max": 1080p es el máximo en todos los modos.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Imágenes clave fuera de rango: más de 4, una imagen o fuerza inválida; un momento fuera del clip, o dos imágenes clave a menos de 0,5 s de distancia; un modo distinto a Calidad (Ultra, Multi-Ref), o una extensión sin consistency enhanced.
400	invalid_consistency, consistency_mode	consistency distinto de standard o enhanced; coherencia reforzada solicitada en Ultra o en Multi-Ref.
400	consistency_explicit	Un prompt que la coherencia reforzada no renderiza aún, de más de 20 s (15 s con end_image), en una extensión o en una secuencia (un solo plano más corto se renderiza en coherencia estándar): acórtalo, o usa standard.
403	consistency_licensed_only	La coherencia reforzada está reservada para licencias.
503	consistency_unavailable	La coherencia reforzada está cerrada por el momento: reintenta más tarde, o genera en standard.
409	consistency_mismatch	Un plano cuyo consistency difiere del de la secuencia.
422	encoding_mismatch	Un render añadido manualmente (POST /sequences/{id}/clips) cuyo consistency difiere del de los planos ya añadidos.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	Una cadencia (fps) que el modo no admite (detail lista las disponibles); coherencia reforzada por encima de 30 fps con duración automática (pon duration_auto a false y proporciona length); una extensión con una cadencia distinta a la del clip anterior.
409	sequence_fps_mismatch	Un plano cuya cadencia (fps) difiere de la de la secuencia.
503	keyframes_unavailable	Las imágenes clave están cerradas por el momento: genera sin keyframes.
429	too_many_sequences	Máximo 5 secuencias en curso por licencia: exporta una, o espera a que una expire.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Un campo de personaje fuera de rango (ver Personajes).
400	image_too_small	Una foto con el lado largo inferior a 1024 px.
415	unsupported_image_format, unreadable_image	Una foto o imagen de decorado que no es un JPEG, PNG o WebP legible.
404	unknown_character	El character_id no está en tu licencia, o fue eliminado (un año sin uso, o borrado en la app).
409	character_limit	Se ha alcanzado el límite de personajes (max): elimina uno.
409	character_busy	Sus vistas se están generando: espera hasta que status deje de ser pending. En POST /characters: la misma creación se está registrando, vuelve a enviarla unos segundos después.
409	photo_view, empty_character, single_image_sheet	La vista generada a partir de la foto original no puede rehacerse; o el personaje no tiene ninguna vista legible (si es el almacenamiento el que rechaza la lectura: 503 storage_unavailable, vuelve a intentarlo); o una sheet importada como una sola imagen (conservada tal cual): sus vistas no se rehacen y no sirve para vestir una sheet nueva (envía la vista 4 o 1).
409	app_character	Una instruction o una vista subida en un personaje o una character sheet hechos en la app: reservado para personajes y character sheets creados a través de la API.
400	instruction_too_long	Una instruction de más de 200 caracteres.
400	outfit_or_views_required	Una character sheet añadida sin outfit ni views: da un outfit que generar, o vistas.
400	views_required	Una character sheet añadida con generate: false: da al menos una vista.
409	source_sheet_empty	Una character sheet añadida sin vista de cuerpo entero ni busto, a un personaje que no tiene ninguno de los dos del que partir: envía uno en views.
404	unknown_sheet	Solo una character sheet añadida a través de la API (sheet_origin api) se borra con DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	El subject_id no está en tu licencia, o fue eliminado tras un año sin uso.
409	subject_limit	Se ha alcanzado el límite de sujetos (max): decorados, objetos, animales, estilos y outfits cuentan juntos; elimina uno.
409	empty_subject	Un sujeto sin ninguna imagen legible.
400	invalid_type, description_too_long, invalid_images	Un campo de sujeto fuera de rango (ver Lugares, objetos, animales, estilos y outfits).
400	invalid_image	Una imagen de sujeto que no es un JPEG, PNG o WebP legible de al menos 512 px en el lado largo (index indica cuál).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Generar un sujeto: ni description, ni prompt, ni imagen de partida; una clave de vista que el tipo no tiene (detail da la lista); count fuera de 1 a 6, o más de 6 imágenes, partida incluida; un prompt de más de 2000 caracteres; instructions vacías, demasiado largas o para varias vistas.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	Ya hay una serie en curso en este sujeto; un sujeto creado con imágenes (añade imágenes con /images); una vista ya hecha (rehazla); una partida que rehacer cuando ya parten vistas de ella; una partida fallida que hay que rehacer primero; una partida importada, que no se rehace.
404 / 503	unknown_view, generation_unavailable	Una vista nunca pedida (añádela); la generación de sujetos no está disponible en el servidor por ahora: vuelve a intentarlo más tarde.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref fuera de rango: de 1 a 4 personajes (12 en Ultra), sin extensión ni transición, los formatos y duraciones de Multi-Ref Vídeo.
400	duplicate_name, invalid_strength, unknown_mention	Dos personajes con el mismo nombre; strength fuera de 0 a 2; un @Nombre en el prompt sin personaje asociado (mentions los lista).
400	voice_requires_audio, voice_slot	Una voz de personaje (voice_b64) sin sonido ("audio": true); o en un personaje distinto de characters[0] y characters[1] (el motor admite 2 voces). index indica cuál.
400	invalid_voice_choice	voice distinto de character u original en un Face swap, o characters[].voice distinto de character o generated en Multi-Ref Vídeo.
413	audio_too_large	Una voz de personaje de más de 4 MB, o de más de 2 MB en un Face swap. Solo se usan los primeros 5 segundos (20 en un Face swap): envía un fragmento corto.
415	unsupported_audio_format	Una voz de personaje que no es un archivo de audio legible (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Más de 4 personajes, objetos y animales en total, fuera de Ultra; un sujeto en el campo equivocado (un decorado en subjects, un objeto como location, un estilo fuera de styles, un outfit fuera de outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Crear una imagen: count 1 o 2, view de 1 a 5 y presente en la sheet, lora_pass de 0,3 a 0,9, la image de un sujeto entre sus imágenes, ancho y alto de 256 a 2048.
400	character_not_ready	Crear una imagen: la vista elegida de un personaje aún no tiene imagen.
503	multiref_image_disabled	Crear una imagen aún no está abierto en este servidor.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Estilos, outfits o movimiento fuera de Multi-Ref en Ultra; más de 30 imágenes en Ultra; un worn_by que no nombra a ningún personaje.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion sin motion_id ni video_b64; un mode distinto de camera o choreography; un vídeo ilegible, o fuera de 4 a 30 s (input_video_out_of_limits); un motion_id nunca subido (sin PUT).
404 / 409	unknown_motion, motion_already_used	Un motion_id desconocido, ya usado o de más de 2 horas: sube el vídeo de nuevo.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	Un vídeo de movimiento de más de 20 MB (20 MB una vez reducido a 480p); el movimiento aún no está abierto (ultra.motion_per_second vale null); un mode aún no abierto.
409	extension_link_expired	Un extend_job_id que tu licencia no conoce, o un plano Ultra de más de 24 horas: sube su original (POST /extensions) y pasa extend_upload_id.
400	extension_real_face	El vídeo que quieres prolongar en Ultra no se renderizó en modo Ultra (el render de otro modo, por ejemplo) y muestra un rostro realista: no se cobra nada. Prolóngalo en modo Calidad, o vuelve a hacer el plano en Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Extensión Ultra fuera de límites: extend_upload_id o backward sin quality: "max" (o desde un clip que no es Ultra); una imagen de inicio, referencias, movimiento o coherencia reforzada con ella; una dirección distinta de forward o backward; backward en una secuencia; extend_video en Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	Un vídeo subido por encima de 1080p; un MP4 ilegible, o fuera de 4 a 30 s (input_video_out_of_limits); un archivo nunca subido (sin PUT).
400	input_video_out_of_limits	Un vídeo enviado al modo Ultra (movimiento, vídeo que prolongar) fuera de sus límites, comprobados antes del render, sin cobro: limit indica cuál (duration: 4 a 30 s; total_duration: 30 s con los sonidos de referencia; count: 10; size: 200 MB; format: MP4 o MOV; fps: 24 a 60; pixels: ancho × alto de 409 600 a 8 295 044; aspect_ratio: 0,4 a 2,5), con value, min y max.
404 / 409	unknown_extension_upload, extension_upload_used	Un extend_upload_id desconocido, de más de 2 horas o ya usado: sube el archivo de nuevo.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	Un archivo de más de 60 MB; la extensión Ultra aún no está abierta (ultra.extend_per_second vale null); hacia atrás aún no está abierta.
413	references_too_large	Las vistas preparadas superan el presupuesto del render: usa menos personajes, o un formato más pequeño.
400	video_required, character_required	Un Face swap sin video_b64, o sin character_id.
413	video_too_large	Un vídeo de Face swap de más de 20 MB: recórtalo o comprímelo primero, o usa la herramienta MCP tendre_face_swap, que admite hasta 95 MB.
415	unreadable_video	El vídeo del Face swap no es un MP4, MOV, WebM o MKV legible.
400	invalid_start, invalid_duration, passage_too_short	Un pasaje de Face swap fuera de rango: start por debajo de 0 o más allá del final del vídeo; duration fuera de 0,5 a 20 s; un pasaje inferior a medio segundo.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Un campo de Face swap fuera de rango: zone distinto de tight, normal o wide; part distinto de full o head; likeness fuera de 0,5 a 2; scene de más de 400 caracteres; description de más de 360; name de más de 60.
413	face_swap_too_large	El pasaje sigue siendo demasiado pesado una vez preparado: indica una duration más corta.
429	server_busy	Nuestro servidor ya está preparando dos vídeos de Face swap: reintenta después de Retry-After (20 s). El enlace de subida MCP devuelve el mismo código como 503 cuando hay demasiados archivos en espera: reintenta en unos minutos.
503	face_swap_unavailable, face_swap_price_missing	El Face swap está cerrado, o sin precio, por el momento: reintenta más tarde.
503	creation_unavailable, multiref_unavailable, storage_unavailable	El servicio no está disponible por el momento: reintenta más tarde.
500	internal_error	Un incidente inesperado en el lado del servidor: reintenta, e infórmanos si vuelve a ocurrir.

Ultra facturado por segundo (Ultra):

Código	error	Qué significa y qué hacer
400	resolution_outside_ultra	Por encima de 1080p: 480p, 720p o 1080p.
400	engine_refused	El motor rechaza el texto o una imagen: el motivo está en detail y el código en code. No se cobra nada: reformula.
502	engine_unavailable	El motor no responde: vuelve a intentarlo en unos minutos. No se cobra nada.
409	render_in_progress	Cancelación de un render que ya se está calculando: ya no se detiene, se entrega y se factura.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref en Ultra: una imagen de referencia es ilegible o demasiado pesada (20 MB como máximo en total), o una opción no es compatible.
403	multiref_ultra_unavailable	Multi-Ref en Ultra facturado por segundo aún no está abierto para esta cuenta.

Los nombres de error son las cadenas exactas que devuelve la API. Compáralos con ellos en lugar de con el mensaje, que puede ser reformulado.

Una respuesta no es un error: un render de Multi-Ref o un Face swap con un personaje que solo tiene una vista sale adelante, con un aviso limited_likeness en warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). El parecido es limitado: crea las siete vistas del personaje para obtener uno fiel.

Un render Multi-Ref en Ultra con 9 a 12 personajes también sale adelante, con un aviso many_characters: algunos pueden faltar o mezclarse (se recomiendan 8).

Buenas prácticas

• Consulta cada 3 segundos, no más rápido. La cola es compartida, y saturarla no ayuda a nadie.
• Descarga en cuanto el estado sea completed. El archivo no se archiva.
• Escribe los prompts en inglés, y para vídeos describe el movimiento en lugar de la imagen estática.
• Una clave por uso, y un límite diario de créditos en cada clave que viva en un servidor. Una clave filtrada con límite te cuesta un día, no todo el saldo.
• Trata un 429 como algo normal, no como un fallo: espera el Retry-After y continúa.
• Una conexión cortada antes de la respuesta no cuesta nada. Si un envío de imagen o vídeo se queda sin respuesta (tiempo de espera de un proxy agotado, error 524, programa detenido), el renderizado no se inicia, o se cancela de inmediato, y no se cobra nada: simplemente vuelve a enviar la solicitud. En un lote de imágenes (count), los renderizados ya creados también se cancelan. La creación de un personaje, en cambio, continúa: reenviar la misma solicitud devuelve el mismo personaje, sin cobrar nada dos veces (ver Personajes).

Los prompts se registran en nuestro lado, igual que en la app, por motivos de seguridad.