OA Workflow Metadata

Ordinary Animator never runs your workflow to find out what it is. It reads a note you leave inside the workflow, and everything the product knows about that workflow -- its name, what it produces, which menu it appears in -- comes from there.

That note is a plain ComfyUI Note node with the title OA Workflow Metadata. Inside it you write one setting per line, in the form field: value. A workflow without that note is imported but cannot be used: it has no name to show, no menu to join, and nothing that says what it makes.

Adding the note to a workflow that does not have one

This is the most common thing wrong with a workflow you built yourself or downloaded from somewhere else. It takes about a minute.

1. Open the workflow in ComfyUI.

2. Right-click on an empty part of the canvas and add a Note node. Any empty space will do -- the note is never connected to anything, and where it sits makes no difference.

3. Rename the node's title to exactly OA Workflow Metadata. In ComfyUI you rename a node by double-clicking its title bar. The spelling and the capitals matter; this title is how the platform finds the note.

4. Click into the note's text area and type the workflow's details, one per line:

   name: Portrait Relight
   description: Relights a portrait from a reference image. Keeps the pose and the face.
   output_tags: image
   category: image_to_image
   

5. Save the workflow in ComfyUI, then import it into your project again from the Workflows view. The re-import is what picks up the change -- editing the file does not update the copy your project already holds.

A note that exists but is empty is the same as no note at all, so do not leave the placeholder text ComfyUI puts in a new note behind.

The fields

Only the fields below are understood. A field the platform does not recognise is treated as a malformed note, and a workflow with a malformed note is dropped from every menu with no error -- so a typo in a field name is worse than leaving the field out. Check the spelling against this list before you save.

Everything here is optional except the first three, which every workflow needs.

Name, description and output tags

Field	Required	What it is
name	Yes	The name shown wherever this workflow appears -- menus, recipe steps, the Workflows view. Write it the way you want to read it: Portrait Relight, not portrait_relight_v3_final.
description	Yes	A sentence or two saying what the workflow does. It is shown when someone is choosing between workflows, so say what makes this one different. For a video workflow, say how long a clip it produces in seconds -- seconds are the only unit that reaches the person choosing.
output_tags	Yes	What the workflow produces, so the result is filed correctly: image, video or audio. Separate several with commas.

Leave name out and the workflow shows up under its file name. Leave output_tags out and the platform does not know what kind of thing it makes, so the result may not be filed where you expect.

Category -- which menu your workflow joins

category is the single line that decides whether your workflow is usable inside the recipes you already have, or sits on its own with nothing able to reach it.

A recipe step offers you every workflow in one category as alternatives to each other. So:

• To sit alongside the workflows you already use, give yours the same category as the one you want it to stand in for. A text-to-image workflow of your own declares category: text_to_image and then appears in the same dropdown as every other text-to-image operation.
• To start a new group, use a name of your own beginning with custom_ -- lower case, with underscores: custom_relight, custom_style_pass. A group with a single workflow in it is perfectly normal.

Exactly one category per workflow. If yours genuinely does two jobs, declare the one you will reach for and make the other a separate workflow.

The categories the platform uses are the operation names you already see in a recipe step: text_to_image, image_to_image, image_to_video, upscale, text_to_speech, and so on. The reliable way to get one right is to open a recipe step, look at the operation you want to sit beside, and use that name.

Two things go wrong here, and both are quiet:

• No category at all. The platform falls back to guessing from the file name (t2i-, i2v-, tts- and so on). Older workflows still land somewhere sensible this way, but it is a guess and you should not rely on it.
• A category that is not recognised -- a typo, or a custom name that does not start with custom_. The workflow then appears in no menu at all, which looks exactly like the workflow failing to import.

Because workflows in a category stand in for each other, the names of their inputs matter too -- see App inputs and outputs.

Voice workflows

A workflow that speaks, converts a voice, or trains a voice profile says so with voice_type. It is what puts the workflow on the voice side of the product rather than the picture side.

Field	What it is
voice_type	One of tts (text to speech), voice-changer (re-voice existing audio), or voice-profile-training (build a reusable voice from samples).
voice_model	Which speech model it is built on, for example chatterbox or qwen3-tts. Used to match your workflow to what is known about that model.
voice_options	Extra synthesis options the model accepts. Model-specific and rarely needed.

A text-to-speech workflow also has to take the right inputs -- see Text-to-speech workflows.

Older workflows sometimes carry a field that used to name a render task. There is no longer such a field: delete that line and use voice_type instead. Left in place it makes the whole note unreadable, so the workflow disappears from the menus rather than merely ignoring the setting.

Fields that shape how a workflow is run

None of these are required. Add one when the workflow genuinely needs it.

Field	What it is
preferred_sizes	The output sizes this workflow is happy with, as a comma-separated list of WIDTHxHEIGHT, for example 1024x1024,1280x720. The size picker offers these.
max_size	The largest output dimension to offer. Use it when a workflow gets slow or fails above a certain size.
resolution_constraint	multiple-of-8 or multiple-of-16, when the model only accepts dimensions on that grid. The size picker then cannot produce a size the model will reject.
default_model_id	For a workflow where you choose the model at run time, which model it starts on.
promptCompilerId	Which model's prompt conventions your prompts should be written for, when this workflow's model has particular habits.
output_path	Groups the files this workflow saves on your own machine by shot, character and so on, instead of dropping them all in one folder.
input_image_1_hint	A short line of help shown in the drop zone for the first image input -- Front-facing portrait, plain background. Number it for each image slot: input_image_2_hint, and so on.
input_image_1_wants	What the slot expects, so the right reference is suggested: for example character-portrait. Numbered the same way.
notes	Free text for yourself: quirks, things you tried, why a value is what it is. Nothing reads it.

When the file itself is the problem

Two failures happen before any of the above can be looked at, and both mean the file rather than its contents:

• The file is not readable as a workflow. This is almost always a copy-and-paste out of a chat window or an editor that truncated it. Export it again from ComfyUI -- Workflow > Export -- and upload that file.
• The file has no nodes in it. An export taken with an empty canvas open. Open the workflow you meant to send, then export.

A workflow exported from ComfyUI as a PNG keeps the graph inside the image, and the platform cannot read it from there. Export as .json instead.

Where to go next

• App inputs and outputs -- the other half of making a workflow usable: what the platform is allowed to fill in
• ComfyUI Integration -- adding your own workflow, and checking it will run where you intend to run it
• Workflows -- the view where you import a workflow and ask the assistant what is wrong with one