create_flow
Create a flow. Provide the models in order — input/output nodes and connections are generated automatically by matching output→input port types, and the original input is shared (fan-out) when several models need it. Set run=true to start it immediately in the same call.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run | No | Start the flow immediately after creating it. Requires input_files when the flow has input nodes. On success the response carries run_status — poll get_flow(view="status") from there. The flow is created either way: if the run cannot start, next_step explains why. | |
| name | No | Name for the new flow. Defaults to the model chain (e.g. 'ModelA → ModelB'). | |
| nodes | Yes | JSON array of models IN ORDER. Two formats: (1) SHORTHAND — a string array of model IDs, e.g. '["ModelA","ModelB"]'. Use this unless you need explicit connections. (2) FULL — node objects with id, type, model_id and optional parameters, e.g. [{"id":1,"type":"ai_model","model_id":"ModelA","parameters":{"steps":50}}]. Use get_model_parameters to discover parameters; anything omitted is filled with defaults. FULL nodes may also declare the input and output nodes themselves — {"id":1,"type":"input","model_id":"Image-Loader"} or {"id":9,"type":"output","model_id":"Image-Viewer"} — which is how you give several models the SAME source (e.g. three editors comparing one image) instead of chaining them. Declaring any input/output node turns auto-generation off: the graph is then exactly what you pass. | |
| parameters | No | JSON object of parameter overrides keyed by model_id, or by node id (the node's id field, NOT its position; shorthand numbers models from 1) to target one node in a chain that repeats a model. Node-id keys win over model_id keys. Dropdown parameters take one of their listed values (the label, e.g. "Image to Video"). A key matching no node, a parameter the model does not declare, or a value outside a dropdown is refused and nothing is created. Example: {"PiSA-SR":{"steps":50,"seed":123}} or {"2":{"resolution":"1080p"}}. | |
| connections | No | JSON array of explicit connections, e.g. [{"out_node_id":1,"out_port_index":0,"in_node_id":2,"in_port_index":0}]. Port indices are positions in the model's own input/output list, and the order is NOT the same across models — some image editors take the image on port 0, others take the text prompt there. Read the ports from get_model before writing indices; a wrong index is rejected with the correct layout in the message. Connections you pass are kept: only the ports you leave open get wired automatically. | |
| input_files | No | JSON array of inputs for the generated input nodes, matched in order. For image/video/sound inputs: file URLs from upload_file. For text inputs (Text-Input nodes): text content directly — it will be auto-uploaded as a text file. Example: ["https://storage.googleapis.com/.../image.png", "Change the color to blue"] | |
| include_optional | No | Whether to auto-generate input nodes for OPTIONAL model input ports. Default true: every optional port also gets its own loader node (e.g. a multimodal model with an optional image input gets an Image-Loader). Set false to scaffold only REQUIRED inputs. DECIDE this yourself from the task — you do not need the user to ask: set false when the goal clearly uses only some modalities (e.g. 'summarize this text' on a text+optional-image model → skip the image loader), or when the user's input_files cover only the required ports. Keep true when the goal is genuinely multimodal, when the user supplied inputs for optional ports, or when you are unsure — so no modality is silently dropped. When in doubt, leave it true (or omit). |