OpenKatana · All tools:
OpenKatanaTool connects your ComfyUI workflow to OpenKatana’s local video-production tools, allowing you to run project operations without switching to a command-line interface or an agent connection. It provides a general-purpose way to access the available tool catalog through the same JSON-based command contract used by OpenKatana’s CLI and MCP integrations. This makes it useful when you want to combine AI-art workflows with local video-production tasks, including the analysis operations exposed by OpenKatana. Execution is local rather than paid or cloud-based. Model jobs return a job identifier instead of keeping the ComfyUI queue occupied until the model finishes. Because project state is shared with OpenKatana Studio, CLI, and MCP, this node is designed to execute again when evaluated rather than reuse a cached result that might no longer reflect your project.
OpenKatana · All tools Input Parameters:
tool
A required dropdown selection that chooses the OpenKatana operation to run. Its available options come directly from the installed OpenKatana TOOLS catalog, so the complete list depends on that installation and is not enumerated in the supplied source. The selected operation determines which information you must provide in arguments, what work is performed, and what result is returned. The supplied API context includes operations such as analyze_energy and analyze_clip, but you should use the actual dropdown and the selected tool’s contract to confirm availability and requirements. No explicit default selection or numeric minimum or maximum is declared.
project_id
A required text value identifying the OpenKatana project associated with the call, with a default of my-film. It is passed to the argument-preparation step alongside the selected tool and your JSON arguments, providing project context before execution. Use the identifier of the project you intend to work with, particularly when coordinating work between ComfyUI and OpenKatana Studio. A project identifier is not a media file path or a display title. The node declares no length limits, allowed-character restrictions, or numeric minimum or maximum; the supplied code also does not establish whether a particular tool creates a missing project or requires an existing one.
arguments
A required multiline text field containing the selected tool’s arguments as a JSON object, with a default of {}. This is where you specify tool-specific settings without adding separate controls to this general-purpose node. The selected operation determines which keys are required, which are optional, and which values are accepted. For example, the supplied analyze_clip signature requires clip_id and an operation chosen from masks, faces, interpolate, or retime, in addition to project context; it also accepts options and apply. The API rejects unsupported argument names and missing required arguments. Use valid JSON with double-quoted property names and lowercase boolean values such as false. No text-length limit or universal numeric range is declared for this field; individual tool settings have their own contracts, and the empty default is only sufficient when the selected operation needs no additional arguments after preparation.
after
An optional string connection used to establish an execution dependency on an upstream node. It is configured with forceInput, meaning you connect a compatible output rather than enter text in a normal widget. Connecting an earlier OpenKatana node’s string result can help ensure that its execution precedes this call, which is useful when several operations depend on shared project state. The implementation accepts after but does not read its content or forward it to the tool, so it does not supply arguments, interpret results, or check whether an asynchronous job has finished. No default value, length limit, or numeric minimum or maximum is declared.
OpenKatana · All tools Output Parameters:
result_json
A string containing the result returned through OpenKatana’s response wrapper. This is the node’s only declared output and is intended to carry the operation’s JSON result rather than a directly usable ComfyUI image, video, or mask tensor. Its contents depend on the tool you selected; the supplied code does not define a single universal response schema. For model jobs, the node description states that a job identifier is returned so ComfyUI can release its queue. Treat that identifier as a reference for checking the job, not as confirmation that processing has finished. If you need particular values for later workflow steps, inspect the returned structure and use a suitable JSON-processing node to extract them.
OpenKatana · All tools Usage Tips:
- Check the selected tool’s signature before writing
arguments. The API validates argument names strictly, so copying names exactly is more reliable than guessing equivalent wording. - Start with only the required tool settings, then add optional settings individually. The default
{}is a starting point, not a complete configuration for every operation. - Use valid JSON rather than Python-style dictionaries: write double-quoted keys and strings,
trueorfalsefor booleans, andnullwhere a tool accepts an empty value. - Keep
project_idconsistent across nodes that work on the same project. If you also include a project identifier insidearguments, verify the argument-preparation behavior first; the supplied source does not show how conflicting identifiers are resolved. - Connect an upstream
result_jsontoafterwhen one project operation must execute before another. For asynchronous model work, check job completion separately, using the available OpenKatana job-status functionality; this connection alone does not wait for the model to finish. - For
analyze_clip, choose an operation frommasks,faces,interpolate, andretime. Its API signature defaultsapplytofalse; review the tool’s documented application behavior before changing that setting. - For
analyze_energy, the supplied signature offersstartanddurationto select a time interval, withstartdefaulting to0anddurationdefaulting toNone. Use a relevant interval when you do not need the entire source analyzed; no numeric limits are provided in the context. - Remember that this node deliberately bypasses normal unchanged-result caching. Before repeatedly queuing a workflow, check whether the selected tool changes project state or starts a new job, because the call can run again even when its visible settings are unchanged.
OpenKatana · All tools Common Errors and Solutions:
Unknown OpenKatana tool
- Explanation: The API raises this message when the requested tool is not present in its
TOOLScatalog. A saved workflow may refer to a tool that is unavailable in the current installation. - Solution: Select an available operation from the current
tooldropdown. If a previously available tool is missing, check that your OpenKatana installation and saved workflow use compatible versions.
TOOL_NAME: arguments must be a JSON object
- Explanation: The API raises this message when the arguments reaching it are not a dictionary-like JSON object.
TOOL_NAMErepresents the selected operation. A JSON list, number, or quoted string is not an object, even if it is otherwise valid JSON. - Solution: Enter an object containing named settings, such as
{"clip_id": "your-clip-id", "operation": "faces"}, with the actual values required by your tool. Use{}only when no additional settings are required.
TOOL_NAME: unsupported arguments: ARGUMENT_NAMES (supported: PARAMETER_NAMES)
- Explanation: One or more argument names do not match the selected tool’s signature. The actual message lists the unrecognized names and the supported parameter names, helping you identify spelling mistakes or settings copied from another tool.
- Solution: Remove unsupported keys or replace them with the exact supported names listed in the error. Do not add extra descriptive fields unless the selected tool explicitly accepts them.
TOOL_NAME: missing required arguments: ARGUMENT_NAMES
- Explanation: The prepared call does not include all parameters required by the selected tool. For example,
analyze_cliprequires a clip identifier and an operation as well as project context. - Solution: Add each listed missing parameter to
argumentsusing the tool’s documented value format. Check that you selected the intended operation and that the project context is correct.
Invalid JSON in arguments — exact message not shown in the supplied source
- Explanation: Malformed JSON can prevent the argument text from being prepared for the API call. Common causes include single quotes, trailing commas, missing quotation marks, and Python-style values such as
TrueorNone. The supplied code does not show the parser’s exact error message. - Solution: Validate the text as JSON, use double quotes around property names and string values, remove trailing commas, and use
true,false, ornullwhere appropriate.
A job identifier is returned, but the expected processing is not finished
- Explanation: This is expected behavior for model jobs, not necessarily an error. The node releases ComfyUI’s queue after returning the job identifier, and the
afterconnection does not check background-job completion. - Solution: Check the returned job identifier with OpenKatana’s job-status functionality before running work that requires the completed result. Distinguish successful job submission from successful job completion.
