Generate Images
lab_generateGenerate an image on the production pipeline (fal.ai, quota-tracked, persisted to the project's gallery). Waits up to wait_s seconds (default 45) for the image and then answers with the finished rows — image_url set, inline previews attached, so the picture is in the answer like lab_job_status with preview. Pass wait_s: 0 to return right away with rows in status 'pending' (poll lab_job_status with id + project_id then). If the budget runs out, the rows come back as they are and fertig: false says so. Default tool is 'flux_pro'; use 'nano_banana_pro' (Gemini 3 Pro Image) for the Papercut-style look. Pass seed_image_url to run img-to-img guided by an existing image URL. get_cost: true preflights credits — it returns the price without generating anything. FOR A PERSON WHO MUST LOOK THE SAME across several images, do not re-describe them per prompt: get an id from lab_list_characters (or build one with lab_create_character + lab_generate_character_reference) and pass it as character_refs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Seed for a repeatable run. Omit it and the project's stored seed applies (POST /api/lab/projects/{id}/einstellungen), and without that the provider picks one. The seed that actually rendered comes back in lab_job_status as `seed` with `seed_quelle` ('provider' = read from the provider's answer, 'gesetzt' = the one sent, null = the model tells no seed). Models whose endpoint has no seed field do not drop a given seed silently: the run proceeds and the row carries `seed_hinweis: seed_nicht_unterstuetzt` — some models tell their seed but take none, others take one but tell none. | |
| tool | No | Image model id — copy it verbatim from lab_list_models (kind: image). Omit to use the default. Every model has its own resolutions, aspect handling and price; the catalog is the only place those live, this text deliberately names none. | |
| aspect | No | Frame as [width, height], e.g. [9, 16]. Overrides the project's pose_state — pass it when the Pose-Director's blockout is set but not yet saved. Measured 2026-07-31: without it a 9:16 blockout came back as 16:9, because pose_state was still NULL. | |
| prompt | Yes | What to generate (required) | |
| wait_s | No | Seconds to wait for the finished image before answering (default 45, max 80). 0 = answer immediately with pending rows. | |
| anker_id | No | Look anchor id (positive integer string) whose CHOSEN image guides this generation as img-to-img. An anchor is a look imported from Midjourney: a handful of images plus the grammar of the old `--profile` code, stored per project. It resolves to exactly ONE image — the one the anchor's `gewaehlt` points at — because the provider payload carries one reference, not a set. So this is MUTUALLY EXCLUSIVE with seed_image_url (two sources for one field), and character_refs still wins over both: identity beats look. Build one from imported images with lab_umzug {anker}; list anchors with GET /api/lab/projects/<id>/umzug/anker. | |
| get_cost | No | Preflight: return the price in credits and your balance WITHOUT generating, reading the same catalog as lab_list_models. Do this before a batch or when the user wants to see the cost. For a card the user confirms, use lab_propose instead. | |
| metadata | No | Free-form JSON stored alongside the image (e.g. { parent_id, note }). Not interpreted by the pipeline. | |
| prop_ids | No | Prop ids from lab_list_props, belonging to this project (an @prop_ tag in the prompt does the same). Their descriptions go into the prompt, and each prop's FRONT view goes along as a reference image — after the characters, before the style kit; a prop alone may switch a text-to-image call to image-to-image (not on the abdruck path). The answer says which way it went (props.weg, props.grund). | |
| variants | No | How many variants to generate (default 1, max 5) | |
| scene_ref | No | Scene label (e.g. 'SZ 04'). Stored on the row, so results can be matched back to a shot list and reviewed per scene with lab_review_queue. Omit it and the image is an orphan. | |
| apply_lens | No | Defaults to TRUE on the backend: the project's lens_state UrPrompt is appended to the prompt. Pass false only to deliberately opt out for this one call. | |
| project_id | Yes | Project id (from lab_list_projects) — generation is always project-scoped | |
| resolution | No | Resolution tier, exactly as listed for the model in lab_list_models. Omit for the model's default; the aspect ratio still comes from the project's pose_state — this only sets the area. Some models have no resolution field at all — then leave it out. | |
| location_id | No | Location board id (from lab_list_locations). Anchors the shot: the board's `prompt_prefix_en` is appended to your prompt as 'Location: …' before generation, so every image of the same place stays in the same place. Check the prefix with lab_list_locations first — a board WITHOUT a prefix anchors nothing and fails silently. | |
| stil_kit_id | No | Style kit id from lab_list_stil_kits (an @stil_ tag in the prompt does the same). Omit it and the project's default kit applies (lab_stil_kit_standard); its rules and palette go into the prompt as text, and its reference images join only where the call already sends reference images (characters or props) and the model has a free slot after them. The answer says which way it went (stil_kit.weg). | |
| aspect_ratio | No | Aspect ratio as W:H (e.g. 16:9, 9:16). Must be one of the model's aspect_ratios where the model has an enum; models without an enum accept any W:H. Omit to use the project's camera aspect. | |
| costume_refs | No | The costume plate of these characters goes along as an extra reference image — the outfit on an invisible mannequin, NO person, so it carries the costume, never the face. Every id must also be in character_refs. Needs a model whose max_references covers characters + plates (lab_list_models); otherwise rejected before any quota is spent. Each plate is one more reference and may cost credits; get_cost prices it. | |
| ohne_stil_kit | No | true switches the project's default style kit off for this one call. | |
| apply_grundton | No | Defaults to TRUE on the backend: the project's ground tone (the filmmaker's own creative signature, set in the Composer's prompt stage) goes right after the prompt. Pass false only to deliberately opt out for this one call. | |
| character_refs | No | Character ids (positive integer strings) whose reference images lock the cast's identity. Routes the call to img-to-img and sends EVERY listed character's reference image, in the order given, up to the max_references (lab_list_models) of the model that actually runs. WITH A CHARACTER, flux_pro — the default — RUNS AS flux_2_pro (FLUX.2 [pro] edit), which takes up to 9 references: the answer names the switch in `umgeschaltet` (von/nach), and get_cost prices flux_2_pro. flux_pro's own img-to-img variant (redux) only varies its source image and dropped the scene in every measured case; it is still used for seed_image_url without characters, where the source's composition is wanted. A model that takes fewer references than you name: naming more with that tool explicitly is rejected before any quota is spent; without an explicit tool the image is made with the first max_references and the answer names the rest in `referenz_warnung` and `referenzen.nicht_gesendet` — nothing is dropped silently. Each additional reference may cost credits; get_cost with character_refs prices exactly that. This OVERRIDES seed_image_url: the characters fill the reference slots, and identity wins over composition. A character without a generated reference image is rejected before any quota is spent. GET IDS FROM lab_list_characters, or create one with lab_create_character followed by lab_generate_character_reference. Prefer character_refs over seed_image_url whenever a person must stay the same across images: seed_image_url holds identity only for the single call that passes it, character_refs is a register entry that every later call can name. SCENE AND LIGHT FOLLOW THE PROMPT: the reference holds the person, not the shot — harbour at night, stairwell under a top light, neon in the rain all came out as asked with the face kept (measured 2026-10-05 on flux_2_pro). What the reference does NOT change is the character's condition: it always shows the BASE state. For a wet, injured or otherwise changed character pass character_states instead of describing it in the prompt (lab_get_character_sheet returns the state keys and the descriptors behind them); to hold the outfit itself, add its costume plate with costume_refs. | |
| seed_image_url | No | Optional: run img-to-img guided by this existing image URL (e.g. a prior generation's url). For a PERSON who must look the same across several images, use character_refs instead — this URL binds one call, a register entry binds all of them. | |
| character_states | No | Which STATE each character is in for this image, as { characterId: stateKey } — e.g. { "12": "wet" }. A state is its own asset with its own full descriptor (clean / soaked / bloodied are three assets, not one with a note), and it is the ONLY way that descriptor reaches a generation: the reference image always carries the BASE state, so without this field you get dry Cal in a scene where he just came out of the Thames — and the image looks correct. Get the keys from lab_get_character_sheet; create one with the character state endpoint. Every id here must also appear in character_refs (who is not in the frame is not described), and an unknown key is rejected before any quota is spent. | |
| dreamer_signatur | No | Proof from the Dreamer (lab_prompt_transform, or the dreamer_fassung of a previous call) that THIS prompt went through it. Without a valid one the tool does not generate: it runs the Dreamer and returns its version first. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |