docs/WORKFLOW_API.md

Workflow API decisions and integration limits

Reviewed against the official Gradio 6.30.0 guide, Python implementation and frontend source on 2026-10-14. PyPI reported 6.30.0 as the current release at review time. The runtime is pinned to this version because Workflow is beta; a future upgrade requires repeating the queue, port, cache and visual checks.

Supported mechanisms used

Need	Actual mechanism
Saved topology	gr.Workflow(graph="workflow.json", bind=...); schema version "2", references/operators/subjects/edges
Bound Python nodes	kind: "fn"; fn exactly matches the bind key
Multiple/media outputs	Explicit port types and output_index; return JSON-serializable file dictionaries for video/image media
Configuration controls	Native number, boolean and choices dropdown ports; main settings required with defaults, advanced ports optional/collapsible
Typed checkpoint view	Native markdown subject, supported by the 6.30.0 renderer and API implementation
Clickable picker access	HTML anchor rendered inside the Markdown subject; preparation ID included in URL; normal new-tab link, no raw URL card
Point transfer	Queue-free same-origin FastAPI save/read endpoints keyed by prepared checkpoint ID
Staged execution	Explicit operator Run, preview/checkpoint subjects, native upstream cache plus server replay cache
Default landing view	Documented ?ui=canvas parameter via root redirect
Owner editing / visitor identity	Native HF OAuth enabled in Space README

custom: true ports in the current schema represent extra provider parameters; they are not an arbitrary custom-component registration mechanism. The examined canvas has number fields rather than a slider specification. Gradio's general Blocks/custom-component ecosystem does not establish a supported component mount point within Workflow. No .select() assumption, private store patch, injected parent script or hidden graph-state update is used.

The native HTML widget uses a sandboxed iframe, so an embedded HTML picker is not assumed to have access to the surrounding canvas's state or session. The working standalone FastAPI implementation is retained. The new bridge improves discoverability and eliminates coordinate transcription while keeping that reliable transport architecture. Its mobile DOM/layout and the rendered anchor button still require browser acceptance on the deployment.

Run and cache semantics

In the reviewed frontend, Run Node gathers all upstream nodes and one hop of downstream nodes. Therefore connecting operator directly to operator can execute the next GPU stage while merely trying to run the current one. This graph interposes real subject outputs. Each result can preview its artifact and relay it on a later explicit stage run.

Normal Run reuses upstream nodes marked completed, non-stale and with available outputs. Shift-click forces upstream execution; global Run executes the whole graph. The generated server pipeline endpoint traverses its connected pipeline and does not have the browser's reuse state. Checkpoint subjects are not execution barriers for a global Run or generated full-pipeline endpoint. Their stop behavior applies to targeted operator runs.

Server caching therefore covers all stage calls. Stage fingerprints include prepared/checkpoint identities, point revision and applicable inputs. Generation A/B also reserves an immutable take slot. An identical call returns its saved result. A changed call targeting an existing completed take fails and asks the user to increment Take. A failed inference attempt is not cached, so it can be retried once its worker has ended. A single process-wide lock protects the original global pipeline/progress state; competing stages now receive a busy error instead of silently waiting behind it. An additional lease prevents new model work while a cancelled or timed-out Viggle call is still active. The app runs one worker, as canonical V22 does.

After a source point save, an already displayed native tracking card is not automatically invalidated; explicit Track Run reads the new revision, and later spatial/A stages reject stale point revisions. After a Recovery frame save, explicit Prepare Recovery Run returns the selected candidate; Pass B rejects an older candidate card. Recovery consumes an already saved A artifact and calls only the original B function. If upstream traversal attempts A with changed settings but an existing take, it stops instead of spending another A job.

The take workspace comes from an HttpOnly same-origin browser cookie, with Gradio session ID/preparation fallback for programmatic callers. Preserve the cookie jar for API calls; a new browser/workspace is a new take namespace. Recovery is optional, not a background trigger. Its checkbox defaults off, as does Standard's separate path. Pass A has no extra global enable switch: pressing its node Run is its explicit generation action.

REST surface

Bound nodes use Gradio's actual queued endpoints:

POST /gradio_api/call/predict_fn_Prepare_Source
body: {"data": ["[{\"path\":\"<uploaded file>\"},0,2,0,true,1,5,10]"]}
GET  /gradio_api/call/predict_fn_Prepare_Source/<event_id>

The data[0] string is an argument-list JSON string because this is Gradio's bound-function protocol, not a user-facing configuration field. The completed SSE payload wraps the function's serialized return list. Other names are predict_fn_Track_Subject, predict_fn_SAM_Camera_Guard, predict_fn_Build_Virtual_Camera, predict_fn_Viggle_Pass_A, predict_fn_Prepare_Recovery, predict_fn_Viggle_Pass_B, predict_fn_Viggle_Standard. Bound endpoints are marked undocumented by Gradio; their registration is visible in /config, whereas /gradio_api/info primarily describes generated public pipeline endpoints.

Use these stage endpoints in order and pass returned checkpoint text (or its exact opaque ID) to the next stage. Programmatic callers must intentionally save valid points/select a Recovery frame between stages. See the actual working upload/queued Prepare/picker round trip in tools/smoke_cpu_server.py.

Route	Purpose
GET /picker/?session=<prepared_id>	New session-aware source picker
GET /picker/api/session/<prepared_id>	Exact dimensions, anchor frames/times/media URLs, saved points
POST /picker/api/session/<prepared_id>/points	Validate and save {preparation_id, coordinate_space, w, h, anchors:[{frame,time,points}]}
GET /picker/	Original standalone picker, byte-preserved HTML
GET /picker/legacy/?session=<prepared_id>	Original interaction code with an appended auto-load/save bridge; available from the checkpoint fallback link
GET /picker/api/manifest?path=..., /picker/anchor/<n>?manifest=...	Original fallback routes
GET /recovery/?checkpoint=<pass_a_id>	Distinct stabilized-input frame browser
GET /recovery/api/<pass_a_id>	Stabilized camera input and original-source time range
POST /recovery/api/<pass_a_id>/select	{"time": absolute_seconds} → exact frame candidate/selection, CPU only
GET /artifact/<id>	Technical checkpoint/provenance JSON

Points are validated against the exact preparation ID, source space, dimensions, original frames/times and 3–12 finite in-bounds points per anchor. Three is a current V22 adapter requirement; the transport itself remains anchors[]. Selecting a frame does not invoke Repaint or GPU generation.

Native UI limits that remain

• There is no supported frame-picker component or external callback into this canvas's cached node state in the examined API. Saving points is automatic transfer on the next Track Run, not an automatic canvas mutation or automatic GPU launch.
• The generated App presents a whole connected pipeline. Shared source/reference inputs connect Standard and Smart into the same generated group. That App cannot express the staged human decisions; the canvas is the intended interface.
• No semantic lane/group schema was invented. Lanes are conveyed through topology, labels and initial positions. Heights are measured by Gradio; geometry changes are viewer-local, and the final rendered spacing/wires are unverified here.
• The native canvas remains pannable on mobile; the standalone picker uses responsive one-column cards and touch/click mapping. Actual touch, browser rendering and 30–40% canvas navigation are unverified for this candidate.
• English labels replace the original Blocks EN/FR toggle in this candidate; no claim of complete language-UX parity is made.
• Gradio 6.30's canvas does not render the bound function's detailed progress messages. The bridge records truthful phases in container logs; the card still shows its native Running status. The native e.data[0] toast after Stop is not patched; cancellation correctness is verified at the queue/backend boundary.

Primary references

• Official Workflow guide, pinned source
• Workflow Python implementation
• Generated workflow API implementation
• Workflow frontend source
• Hugging Face ZeroGPU
• Gradio Spaces
• Spaces OAuth
• Hugging Face Jobs

The public guide URL returned a fetch error during research, so the official repository's pinned guide/source and the installed 6.30.0 wheel were inspected directly. General ZeroGPU recommendations do not replace V22's intentional pre-fork CPU initialization and scheduler compatibility code.