docs(partner-nodes): generated Code pages for every Router-addressable partner model - #1533
Open
mattmillerai wants to merge 22 commits into
Open
docs(partner-nodes): generated Code pages for every Router-addressable partner model#1533mattmillerai wants to merge 22 commits into
mattmillerai wants to merge 22 commits into
Conversation
Adds the Comfy Router documentation set and the Comfy API v2 spec update that the comfy-pr-bot sync PRs have been carrying, consolidated into one branch: - comfy-router-quickstart.mdx: shortest path to a Router call (new) - comfy-router-reference.mdx: generated Router API reference (new) - comfy-router-limitations.mdx: Router limits and alternatives (new) - openapi-v2.yaml: job logs event + JobLogs schema (updated) - docs.json: register a Comfy Router group under API Development (en nav; zh/ja/ko left unregistered until translations exist) Source PRs (left open): #1483 #1487 #1488 #1489 #1490 #1492 #1497 #1500 #1505 Content taken from the latest state in #1505.
Keep API documentation out of the repo root: move the three Router pages to api-reference/comfy-router/, update cross-page links and the docs.json nav paths accordingly.
…nslations - quickstart: full cURL call example (aligns quickstart with the Python/TS/cURL split in BE-8327); the existing curl snippet only fetched a model schema - api-reference/v2/overview: short 'Comfy Router' pointer section so API v2 readers can discover the Router docs, translated to zh/ja/ko - translate comfy-router quickstart/reference/limitations to zh/ja/ko via translate-i18n.ts - docs.json: register Comfy Router group under API Development for all four locales (en/zh/ja/ko)
…ontract sync - Remove all em dashes from hand-written Router pages (EN) - quickstart: TypeScript COMFY_API_KEY fail-fast to match Python; fix response-handling comment (body parsed before response.ok check) - overview(v2): note Comfy Router is not yet generally available - ja/zh/ko: translate pending setup lines, limitations sections, reference auth sentence and new response rows - fixes broken heading/anchor merges in ja/zh/ko reference.mdx - ja/zh/ko limitations: fix anchor slugs + translate English sections - zh limitations: full-width quotation marks - reference.mdx: regenerate from cloud contract - X-API-Key auth + POST 401/429/500 responses (mirrors router-openapi.yaml)
…the Router docs Bring the Comfy Router pages up to the latest comfy-pr-bot sync state so the superseded per-commit sync PRs (#1509 #1513 #1514 #1516 #1517 #1518 #1519 #1522 #1524) are all carried by this one branch. - reference.mdx: replaced verbatim with the generated file from cloud@2a369ae (GET /v1/models 403/503 rows, POST 429 committed-spend headers + 504 Retry-After, If-None-Match on the schema route, Retry-After and X-Committed-Spend-* header rows, deadline_exceeded retry guidance, no fal attributions, no planned queued endpoint). This drops the hand-edited "X-API-Key or Bearer" auth line: the file is generated upstream and must not carry local edits. - quickstart.mdx / limitations.mdx: 3-way merged the upstream changes onto this branch's edits (relocated links, cURL section, no em dashes): auth Note (comfyui- keys accepted in X-API-Key or Authorization: Bearer), new "Find a model" catalog section, new "Requests are rate limited per caller" section + at-a-glance row, queued-endpoint sentence removed, fal/FastAPI -> FastAPI. - ja/zh/ko: hand-translated the same deltas, un-glued the endpoint ### headings from the preceding table rows in reference.mdx (CodeRabbit finding), and re-stamped translationSourceHash/translationBlockHashes with the repo's chunked-translate helpers (getSectionSyncStatus reports up-to-date for all nine files). - openapi-v2.yaml already matched cloud@2a369ae; no change. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…text Splits the Kontext page into three tabs so a reader can pick the path that fits them: read about the model, load a ComfyUI workflow, or call it over HTTP through Comfy Router. The Code tab gives Python, TypeScript and cURL snippets per variant (Pro, Max) plus the native result shape, and shares the pre-GA notice and production checklist through two new snippets so the same layout can roll out to the other partner model pages without re-authoring the boilerplate.
|
Warning Review limit reachedNext included review available in 28 minutes. View limit detailsLimit details: You’ve used the included review currently available. Your 130 included PR review attempts over the past 7 days set your current allowance at 1 review per hour. Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. Review configuration: ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (53)
Comment |
mattmillerai
changed the title
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
🌐 i18n translation sync reminder@comfyui-wiki English documentation was updated in this PR. Please complete or schedule translation updates for the following files: Japanese (
|
Comfy Router's model routes moved from /v1/models to /v2/models upstream (cloud #7646), so the pilot snippets follow the live contract.
The Code sub-page is meant to be identical in shape across every partner model, so the shape should live in one place. code.mdx is now rendered by .github/scripts/snippets/gen-code-pages.ts from a small code.yaml next to it (name, Router model IDs, example body, result path); Python, TypeScript and cURL are emitted from the same example so they cannot disagree. A new workflow fails a PR when a generated page is stale or an emitted snippet does not parse. Adding a model becomes a 15-line spec plus one command.
…model Extends the Kontext pilot to every partner-model page whose model Comfy Router can address today. The catalog only admits proxy routes that name their model in the path, so that is nine pages: Flux 1.1 Pro Ultra (with FLUX 1.1 [pro]), Flux.1 Kontext, FLUX 3 Video, FLUX Video Upscale, Nano Banana Pro, Nano Banana 2, Nano Banana 2 Lite, Ideogram 4.0 and Google Gemini. Each gets a code.yaml, a generated code.mdx, a docs.json entry and a second card on its overview. The generator grows what those specs needed: a per-variant request body (Ultra and the standard model take different inputs), nested bodies rendered as real Python and TypeScript literals (the Gemini generateContent shape), result paths with array indices, and a result label so video, text and base64 image results print correctly. Not addressable yet, so no Code page: Ideogram P-Image (multipart body), Kling 3.0 (two proxy routes claim kling/kling-3.0-turbo, so the catalog marks it ambiguous), Krea (slash in the vendor id) and every model that declares itself in the request body (OpenAI, ByteDance, Luma, Runway, Recraft, Bria, Grok, Topaz, Wan, MiniMax, Moonvalley, the 3D, audio and LLM providers other than Gemini).
mattmillerai
changed the title
…e pages Mintlify uses the code fence title as the CodeGroup tab label, so bare fences rendered three unlabeled tabs and only the first (Python) snippet was discoverable. The template now titles each fence, which relabels all nine generated pages at once.
Two spaces between the two inline-code spans is not a markdown line break, so long model IDs wrapped mid-URL and ran the two labels together.
…snippets The Python and TypeScript tabs now call comfy-sdk's client.models.run and @comfyorg/sdk's comfy.models.run instead of hand-rolling the HTTP call, so the snippets show the supported path and inherit the SDKs' idempotency key, 10 minute deadline and request-id handling. cURL stays as the raw HTTP reference. The shared footer now says which of the production concerns the SDKs already cover.
… pages
Each generated Code page now ends with Input schema, Input example, Output
schema and Output example, the four sections fal's per-model pages carry.
They render from router-schemas/<provider>/<model>.json, the exact body of
Router's GET /v2/models/{id}/openapi.json, so the table is the schema the
server enforces. No model has an authored schema on Router yet, so every
page currently renders the fallback: the spec's hand-written fields and
examples plus a note that Router has not published the schema. Variants
that share a schema share a block; variants that differ get tabs.
…ctions Matches fal's layout: one Schema section with Input and Output, one Examples section with Input and Output, instead of four top-level sections.
…page Mintlify syncs tabs with matching titles, which is the right behaviour for a model-variant picker but reads as a glitch when nothing says so.
…d tables Input and Output now render as Mintlify ParamField / ResponseField lists (name, type, required, default, description, possible values, range), the same shape fal's per-model pages use. Each code.yaml carries the provider's documented input and output as JSON Schema; that is the fallback source until Router publishes the model's own schema, at which point router-schemas/<id>.json takes over with no template change. The orphaned openapi.json curl block is gone; the note names the endpoint.
…e page Pages with more than one Router model now have a single tab bar at the top, as fal's per-endpoint pages do; Quick start, Schema and Examples all live inside the selected tab, so no section carries its own tab bar and nothing has to be synced. Single-model pages render the same body with no tabs at all.
… TOC check-provider-schemas.ts fetches each provider's own published API specification (BFL and Ideogram OpenAPI, Google's discovery document) and fails CI when a documented field, type, default, enum, bound or required flag disagrees with it. Its first run found real drift, now fixed: Kontext defaults to png and allows webp, input_image is optional and up to four reference images are accepted, safety_tolerance goes to 6; FLUX 3 Video defaults to fhd; Video Upscale's creativity is 0 or 1 and upscale_factor is 1.5 to 3; Ideogram's response has no style_type; Gemini declares no sampling defaults. The in-page note shrinks to one line now that the fields are tested rather than trusted. Headings inside variant tabs duplicated in the table of contents and sent clicks to hidden anchors. Pages whose variants share a schema now render Schema and Examples once, outside the tabs; pages whose variants differ use HTML headings inside the tabs so the TOC does not index them.
One place for what is the same across every Router model: the request headers a caller sends (API key in either header, Idempotency-Key, If-None-Match) and the response headers Router returns (request id, error bucket, replay marker, Retry-After, committed-spend, schema caching), plus the three statuses that carry two buckets and what Router deliberately does not offer as headers. The per-model footer shrinks to one paragraph that links here instead of restating it on every page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a third sub-page, Code, next to Overview and Workflow for every partner model that Comfy Router can address today, with fal-style SDK snippets: Python via
comfy-sdk(client.models.run), TypeScript via@comfyorg/sdk(comfy.models.run), and cURL as the rawPOST /v2/models/{provider}/{model}reference. The pages are generated from a per-modelcode.yamlby one template, so a change to the page shape is a change in one file.Stacked on #1508 (
docs/comfy-router-docs) so the Router quickstart and reference links resolve in the preview; the diff shows that branch's files too until it merges. #1536 moves those pages to/v2/models; the snippets here already use/v2.Preview (Kontext, others at the same path pattern): https://dripart-docs-router-model-page-pilot.mintlify.site/tutorials/partner-nodes/black-forest-labs/flux-1-kontext/code
Pages
bfl/flux-pro-1.1-ultra,bfl/flux-pro-1.1(different bodies)result.sampleimage URLbfl/flux-kontext-pro,bfl/flux-kontext-maxresult.sampleimage URLbfl/flux-3-videoresult.samplesigned MP4 URLbfl/video-upscale-v1result.samplesigned MP4 URLvertexai/gemini-3-pro-imagecandidates[0].content.parts[0].inlineData.database64vertexai/gemini-3.1-flash-imagevertexai/gemini-3.1-flash-lite-imageideogram/ideogram-v4data[0].urlvertexai/gemini-3.1-pro-preview,gemini-3.5-flash,gemini-2.5-pro,gemini-2.5-flashcandidates[0].content.parts[0].textModel IDs come from the Router catalog as derived by
services/comfy-api/server/middleware/router_model_catalog.goat cloudmain(dumped, not guessed). Request bodies follow each provider's native API.Not addressable by Router today, so no Code page yet (each becomes a spec plus one command once it is):
multipart/form-data, not JSON.kling/kling-3.0-turbo, so the catalog records it as ambiguous and the route answersmodel_not_found.krea-2/large), outside the{provider}/{model}alphabet.Page shape
Each Code page: intro and the shared not-GA notice; Quick start with the Model ID, the endpoint, a variant switcher where the page covers more than one Router model, and a
CodeGroupof labelled Python / TypeScript / cURL tabs; then Input schema, Input example, Output schema, Output example (fal's four sections); then the shared "Before you ship" footer (idempotency key, deadline, request id, 422, links to the Router quickstart, reference and limitations).The schema sections render from
router-schemas/<provider>/<model>.json, the exact body of Router'sGET /v2/models/{id}/openapi.json, so the table is the schema the server enforces. No model has an authored schema on Router yet (openapi.ymlat cloudmaincarries zerox-comfy-router-model-idcomponents), so every page currently shows the fallback: the spec's hand-written fields and examples with a note that Router has not published the schema. The authored path is exercised against a fixture; Router-side work to fill it is tracked separately (authoring the input schemas, and a spike for output schemas plus the bot sync of per-model documents intorouter-schemas/).Headers page
api-reference/comfy-router/headers.mdx(new, in the Router nav next to quickstart / reference / limitations): the request headers a caller sends (X-API-KeyorAuthorization: Bearer,Idempotency-Key,If-None-Match) and the response headers Router returns (X-Comfy-Request-Id,X-Comfy-Error-Type,Idempotent-Replayed,Retry-After,X-Committed-Spend-*,ETag,Cache-Control), the three statuses that carry two buckets, and what Router deliberately does not offer as headers. The per-model footer shrinks to one paragraph that links here. Authored docs-side for now; it should move to cloud'sservices/comfy-api/docs/and ride the bot sync like the other three Router pages so it cannot drift from the spec.Generator
.github/scripts/snippets/gen-code-pages.ts(bun, no dependencies): renders everytutorials/partner-nodes/**/code.yamlinto itscode.mdx. Python (comfy-sdk), TypeScript (@comfyorg/sdk) and cURL (raw HTTP) are emitted from the sameexampleobject (per-variantexamplewhen the variants take different bodies); nested bodies become real Python and TypeScript literals;"@file:<path>"becomes a base64 file read; result paths support array indices;result.labeldrives what the snippet prints (image,video,text,image (base64)).--checkfails on a stale page,--validatecompiles each emitted snippet (py_compile,bun build,bash -n) without executing anything..github/workflows/code-pages-check.yml: runs--check --validateon PRs touching a spec, a generated page,router-schemas/, the shared snippets or the generator.package.json:pnpm code-pages:gen,pnpm code-pages:check. README in.github/scripts/snippets/.snippets/comfy-router/preview-notice.mdx(not-GA note) andsnippets/comfy-router/model-code-footer.mdx(which production concerns the SDKs already cover, and what a raw HTTP caller must do).Also touched:
docs.json(one…/codeentry per page, English nav), and each overview's "Use it in ComfyUI" block becomes a two-card "Use it" (workflows + code) with a pricing/concurrency pointer.Not in this PR: ja/zh/ko (the locale navs in #1532 were not split either), and live (billed) verification of the snippets, which needs Router to be GA and belongs with the existing nightly Router jobs in cloud; the
code.yamlfiles are the case table for that job.ELI5
Each partner model page now has three parts: what it is, how to run it in ComfyUI, and how to call it from your own code. The third part is new. Rather than hand-write it for each model, you fill in a short spec (which model IDs, what an example request looks like, where the result is) and a script writes the page in three programming languages from one template, using our own SDKs. CI refuses a page that was edited by hand or drifted from its spec, so every Code page has the same shape and the three snippets always send the same request. Nine models get the page now; the rest are waiting on Router being able to address them by name. Each page also has the input and output schema sections fal shows; those fill in automatically once Router publishes the schemas.
Testing
pnpm code-pages:check: 9 pages fresh, 27 emitted snippets compile.router-schemas/bfl/flux-kontext-pro.jsonin the served document shape (table, example, per-variant tabs), then removed so no hand-written schema is committed.npx mint broken-links: no broken links.docs.jsonparses; each Code entry sits next to its Workflow entry./v2/modelsroutes).