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
TableJSON 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. | |
| 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. | |
| 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. | |
| 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. |