App Inputs and Outputs
What the platform is allowed to fill in when it runs your workflow, what to call each one, and which ones are filled in for you.
A workflow you run from a recipe is not run as it stands. Ordinary Animator fills things in first -- the prompt you typed, the reference image you dropped on the step, the size you picked -- and then submits it. App inputs are how a workflow says which of its settings may be filled in that way.
An App input is a setting that already exists on one of your nodes: the prompt box on a text node, the file field on a Load Image node, the width on an empty-latent node. Marking it as an App input does not add anything to the graph. It says "this one is not fixed -- the app supplies it".
App outputs are the other end: which node produces the result worth keeping, so the platform knows what to collect and put in your gallery.
You set both in ComfyUI's App builder, and save. A workflow with no App inputs at all still runs in ComfyUI, but in Ordinary Animator it cannot be given a prompt or an image, so a recipe step bound to it has nothing to fill in and every run produces the same thing.
What an App input is -- and what it is not
The App input is the loader's or the node's own setting. When you mark the file field on a Load Image node as an App input, the platform hands that node the image directly.
An older way of building the same thing was to put a separate little text node next to the loader, feed its value in, and expose that instead. It works in ComfyUI, but it is the indirection that turns a file name into a path -- and a path is not what the platform supplies. If you have one of those, delete it, mark the loader's own field instead, and give the input the same name the old one had so anything already using it stays connected.
A text node feeding something that is not a media loader -- a fixed piece of prompt text, a naming prefix -- is fine and common. It is only the media loaders that care.
Use the names everything else uses
Every App input has a name, and the name is not decoration: it is how a recipe step keeps its settings when you swap one workflow for another.
Because a recipe step offers you every workflow in a category, someone can replace the workflow in a
step with yours. When they do, each value moves across by name. Positive Prompt lands in
Positive Prompt. An input with no counterpart in the new workflow is parked, not lost -- but
nothing lands in it either, so the step has to be filled in again by hand.
So use the names already in use:
| Use this name | For |
|---|---|
Positive Prompt |
The main prompt |
Negative Prompt |
What to avoid, where the model supports it |
Input Image 1, Input Image 2 |
Images the step feeds in, numbered in the order they matter |
Input Video 1 |
A video the step feeds in |
Output Width, Output Height |
The size of the result |
Output Aspect Ratio |
The shape of the result, for a node that offers a list of shapes instead of a width and a height |
Voice Reference Audio |
The audio clip a voice is copied from |
The quickest way to get this right is to open a workflow already in the category you are declaring, look at what its inputs are called, and use the same names. A name that is gratuitously different costs whoever swaps your workflow in a manual re-wire; it does not stop your workflow working.
A text or number input left blank keeps the workflow's own value. A blank Negative Prompt runs
with the negative prompt saved in the workflow, and a blank Output Duration with the workflow's
own duration. The exception is Positive Prompt: a blank one is sent empty, never the sample prompt
the workflow's author left in the file.
Names ending in a media word decide how the input is presented, too: an input whose name ends in image, video or audio becomes a drop zone rather than a text box.
The size of the result
Whoever runs a workflow that makes a picture must be able to say how big, or what shape, it is. A workflow that fixes its size inside the graph makes the same picture shape every time, and the only fix is to open it in ComfyUI.
So when the node that creates the picture has a size setting -- a width and a height on an empty
latent, say -- mark both as App inputs and name them Output Width and Output Height. A size that
is simply passed along from an input picture (an edit that keeps its source's shape) needs nothing.
Some nodes do not take a width and a height. Gemini's image node takes an aspect ratio from a
fixed list (1:1, 3:2, 16:9, 21:9 and so on). Mark that setting as an App input and name it
Output Aspect Ratio. The person running it still picks an Output Size like for any other
image operation. OA turns it into the nearest ratio the node offers: Full HD gives 16:9, and a
Custom size such as 1664 x 928 is snapped to 16:9 with a line under the size saying so. Leave the
size alone and the workflow runs with its own setting, as it always did.
The import check warns when a picture-making node's size setting is neither an App input nor passed along from upstream. Every workflow OA publishes passes it.
A media input left empty
A drop zone you do not fill is not sent as a blank. Before the job goes out, the loader behind that input is taken out of the graph, along with any scaling or encoding that fed only it -- so a workflow that offers three reference images runs perfectly well on two, and you never have to duplicate a picture into a slot you did not want.
Where the graph cannot do without the input -- the node it feeds requires it, or another picture passes through the same node -- there is nothing to take out, and the run is refused before it starts, naming the input that is empty. That is deliberate: the alternative is a job that is accepted, runs for several minutes, and then fails with a message about file permissions that says nothing about a missing picture.
An input that takes a list of images
Some models take several reference images, and how many is up to the person running it, not up to the workflow. Rather than publishing one workflow per count -- two references, three references -- declare the numbered slots as one list input, and the form shows one drop zone for each picture provided plus one empty one underneath. Fill the empty one and another appears. Take a picture out and the ones below it move up, so the list never has a hole in the middle.
Build it the way a fixed-count workflow is built: give the graph as many loaders as the model
accepts at most, and name them Reference Image 1, Reference Image 2, Reference Image 3 -- the
same base name, numbered from 1, with no gaps. Then add one line to the OA Workflow Metadata note:
list_inputs: Reference Image 1-3
Reference Image is the name without the number. 1 is the fewest pictures the model needs and
3 is the most it accepts, which has to be the number of numbered slots the graph carries. Several
lists go on the same line, separated by commas.
What the person running it sees is one heading, Reference Image, with as many drop zones as they
have filled and one more. What the model receives is the pictures they provided, in the positions
they appear in, with nothing left over: the loaders for positions nobody filled are taken out of
the graph before the job is sent, along with the scaling and encoding that fed only them. That
matters for models whose prompt refers to pictures by position -- <Image 1>, <Image 2> -- since
a gap in the middle would silently shift every picture after it.
Two things to check when you build one:
- The minimum is a real requirement, not a formality. If position 1 does something the others do
not -- setting the output size, say -- the minimum is 1, because taking it out would break the
rest of the graph. A minimum of
0says the whole list is optional, which is right when something else in the workflow can carry the job on its own -- References to Video (MiniMax H3) declaresReference Image 0-9, because its blocking video already supplies the camera move and the staging, and reference pictures only add character identity. - Positions past the minimum have to be genuinely optional in the graph. Wherever the extra pictures arrive -- the node that combines them, the one that turns each into a reference -- that connection must be an optional one. If a node cannot run without all of them, the workflow cannot take a shorter list, and the platform says so rather than sending a job that fails part way.
Lists work the same way for video, audio and mask inputs.
Seed and Filename Prefix are filled in for you
Two inputs are handled by the platform. One of them you can see; neither needs you to type a value.
Seed. A run has one seed. Every sampler in your graph whose seed control is set to
randomize receives it, whether or not you exposed that seed as an input, and whether the sampler
sits at the top of the graph or inside a subgraph. A sampler whose control is fixed keeps the
seed you gave it: that is how you tell the platform a seed is deliberate. Unless the user set one in
the panel's Seed row, every run draws a fresh seed, which is why running the same step twice gives
two different pictures rather than the same one; a seed set in the row is used exactly, on every
randomize sampler at once, so several samplers that must agree do. You may still name a seed input
Seed to make it an App input; it changes nothing about the rule above.
Filename Prefix. Where the result is saved, and how the platform works out which output belongs
to which step. Name it Filename Prefix and leave it alone. A workflow that saves more than one
kind of result names each one -- Filename Prefix #img1, Filename Prefix #mask -- and the part
after the # becomes the label you see on that output in the recipe step.
Do not type values into either of these, and do not leave them out: they are inputs the platform expects to fill.
Clip length is deliberately not an App input. A frame count is not a free number -- each video model accepts only certain values -- so you do not set one. A workflow states its length in its description, in seconds, and you get a shorter result by setting the shot's duration and a longer one by chaining clips together.
A lipsync clip is as long as its line. This is about seconds, not frames: a workflow that has both a Dialogue Audio input and an
Output Duration input takes its length from the audio when you leave Output Duration empty. The
field shows the length it will use, for example "5.44 s, from the line", and you can type over it.
A value you type always wins; if it is shorter than the line, the field warns you that words will be
cut off, but the run is not blocked.
App outputs -- where the result comes from
Mark the node that saves the result as an App output. Without it the platform does not know which node produced the thing worth keeping, so a run can finish successfully and still put nothing in your gallery.
One save node is the normal case. If your workflow saves two different things -- a picture and its
mask, say -- mark both, and give each one's naming prefix its own #label as above, so the recipe
step can show them separately and a later step can take just the one it wants.
When an input points at something that is not there
If you delete or replace a node after setting up the App inputs, an input can be left pointing at a node that no longer exists. The workflow still opens in ComfyUI, but the platform has nothing to put that value into, and the failure looks like the value being ignored.
The fix is the same either way: open the workflow in ComfyUI's App builder, set the App inputs again against the nodes that are actually there, save, and import it into your project again.
Text-to-speech workflows
A speech workflow declares voice_type in its
OA Workflow Metadata, and it also has to take the
inputs the rest of the product expects. There are two shapes, and a text-to-speech workflow should
be one of them:
- A voice copied from a sample. The workflow takes the text to speak and an audio clip of the
voice: name the inputs
TextandVoice Reference Audio. The audio input is presented as a drop zone, so a character's recorded sample can be dropped straight on it. - A voice picked from a list. The workflow takes the text to speak and the name or id of one of
the model's built-in speakers: name the inputs
TextandVoice Id. That one is presented as a text box.
The other two voice types need inputs too. A voice-changer workflow takes Source Audio (the
audio to re-voice) plus one of the two voice inputs above, and a voice-profile-training workflow
takes Reference Audio.
Where to go next
- OA Workflow Metadata -- the note that says what your workflow is
- ComfyUI Integration -- adding your own workflow, media loaders, and checking the nodes exist where you will run it
- The Media Gallery -- how you choose an operation and fill it in