diff --git a/development/api-development/getting-an-api-key.mdx b/development/api-development/getting-an-api-key.mdx index 670599049..72323c668 100644 --- a/development/api-development/getting-an-api-key.mdx +++ b/development/api-development/getting-an-api-key.mdx @@ -1,6 +1,7 @@ --- title: 'Getting an API Key' description: 'Learn how to create and manage your Comfy Platform API Key for accessing Cloud APIs, Partner Nodes, and more.' +icon: 'key' --- import GetApiKey from '/snippets/get-api-key.mdx' diff --git a/development/api-development/overview.mdx b/development/api-development/overview.mdx new file mode 100644 index 000000000..f365ec469 --- /dev/null +++ b/development/api-development/overview.mdx @@ -0,0 +1,48 @@ +--- +title: "APIs Overview" +description: "An overview of the different ways to interact with ComfyUI programmatically" +icon: "list" +--- + +ComfyUI offers several API options depending on where you want to run your workflows and how much infrastructure you want to manage. This page helps you choose the right approach. + +--- + +## Which API Should I Use? + +| | Cloud API | ComfyUI Server API | +|---|---|---| +| **Where it runs** | Comfy Cloud (managed GPUs) | Your own machine | +| **GPU management** | Handled for you | You manage your own hardware | +| **Models** | Pre-installed and managed by Comfy | You download and manage locally | +| **Authentication** | `X-API-Key` header (Comfy Cloud account) | None (local) or API key for Partner Nodes | +| **Base URL** | `https://cloud.comfy.org` | Your server URL (e.g. `http://localhost:8188`) | +| **Protocol** | REST + WebSocket | REST + WebSocket | +| **Pricing** | Subscription-based (Creator/Pro tiers) | Free (your own compute) | +| **Best for** | Quick integration, no infrastructure | Full control, custom hardware & models | + +Both APIs use the same workflow format ([API format](/development/api-development/workflow-api-format)), so you can develop and test workflows locally and move them to the cloud without changes. + +--- + +## Getting Started + + + + Run workflows on Comfy's managed infrastructure. No GPU setup required. + + + Run ComfyUI as a server on your own machine and call it via API. + + + Use paid Partner Nodes in headless or API-driven workflows. + + + +--- + +## Prerequisites + +Before using any API, you'll need: + +- An API key (see [Getting an API Key](/development/api-development/getting-an-api-key)) diff --git a/development/api-development/workflow-api-format.mdx b/development/api-development/workflow-api-format.mdx new file mode 100644 index 000000000..b3da0a30c --- /dev/null +++ b/development/api-development/workflow-api-format.mdx @@ -0,0 +1,170 @@ +--- +title: "Workflow API Format" +description: "Understanding the API format for ComfyUI workflows and how to export them" +icon: "file-code" +--- + +ComfyUI workflows are JSON objects that describe a graph of nodes. When calling ComfyUI programmatically — whether through the Cloud API or running your own server — the workflow must be submitted in **API format**, a specialized JSON structure that differs from the regular save format used in the browser. + +This page explains the differences and how to export your workflows correctly. + +--- + +## Save Format vs API Format + +The ComfyUI frontend can save workflows in two formats: + +| | Save Format | API Format | +|---|---|---| +| **File menu** | `File → Save` or `Ctrl+S` | `File → Export Workflow (API)` | +| **File extension** | `.json` | `.json` | +| **Node keys** | Node titles or labels | Numeric node IDs | +| **Widget values** | Included | Included | +| **Position/layout data** | Included (x, y, width) | **Excluded** | +| **Colors/groups** | Included | **Excluded** | +| **Usage** | Re-opening in the frontend | API submission | +| **Can be loaded in UI** | Yes | Yes, but without layout | + +The key difference: **API format omits UI metadata** (positions, colors, groups, node sizes) that is only needed for visual editing in the frontend. This keeps the JSON smaller and cleaner for programmatic use. + +--- + +## How to Export + +Open your workflow in the ComfyUI frontend, then navigate to `File → Export Workflow (API)`: + + + Saving a workflow in API format + + +This will download a `.json` file containing only the API-relevant data: + +```json +{ + "3": { + "inputs": { + "seed": 156680208700286, + "steps": 20, + "cfg": 8, + "sampler_name": "euler", + "scheduler": "normal", + "denoise": 1, + "model": [ + "4", + 0 + ], + "positive": [ + "6", + 0 + ], + "negative": [ + "7", + 0 + ], + "latent_image": [ + "5", + 0 + ] + }, + "class_type": "KSampler", + "_meta": { + "title": "KSampler" + } + }, + "4": { + "inputs": { + "ckpt_name": "v1-5-pruned-emaonly-fp16.safetensors" + }, + "class_type": "CheckpointLoaderSimple", + "_meta": { + "title": "Load Checkpoint" + } + }, + "5": { + "inputs": { + "width": 512, + "height": 512, + "batch_size": 1 + }, + "class_type": "EmptyLatentImage", + "_meta": { + "title": "Empty Latent Image" + } + }, + "6": { + "inputs": { + "text": "beautiful scenery nature glass bottle landscape, , purple galaxy bottle,", + "clip": [ + "4", + 1 + ] + }, + "class_type": "CLIPTextEncode", + "_meta": { + "title": "CLIP Text Encode (Prompt)" + } + }, + "7": { + "inputs": { + "text": "text, watermark", + "clip": [ + "4", + 1 + ] + }, + "class_type": "CLIPTextEncode", + "_meta": { + "title": "CLIP Text Encode (Prompt)" + } + }, + "8": { + "inputs": { + "samples": [ + "3", + 0 + ], + "vae": [ + "4", + 2 + ] + }, + "class_type": "VAEDecode", + "_meta": { + "title": "VAE Decode" + } + }, + "9": { + "inputs": { + "filename_prefix": "ComfyUI", + "images": [ + "8", + 0 + ] + }, + "class_type": "SaveImage", + "_meta": { + "title": "Save Image" + } + } +} +``` + +--- + +## Converting Between Formats + +If you have a save-format workflow and need it in API format, the simplest method is: + +1. Open the `.json` file using `File → Load` in the frontend +2. Export it via `File → Export Workflow (API)` + +For automated conversion, you can write a script that strips the `x`, `y`, `width` fields from each node and removes the `groups` and `extra` sections from the root JSON. + +--- + +## Related Pages + +- [APIs Overview](/development/api-development/overview) — Compare Cloud and Server API options +- [Cloud API Overview](/development/cloud/overview) — Submit API-format workflows to Comfy Cloud +- [API Examples](/development/comfyui-server/api-examples) — See API-format workflows in action +- [Getting an API Key](/development/api-development/getting-an-api-key) — Required for Cloud API and Partner Nodes diff --git a/development/cloud/api-reference.mdx b/development/cloud/api-reference.mdx index ad51ab161..13cbf6659 100644 --- a/development/cloud/api-reference.mdx +++ b/development/cloud/api-reference.mdx @@ -1,6 +1,7 @@ --- title: "Cloud API Reference" description: "Complete API reference with code examples for Comfy Cloud" +icon: "book-open" --- import PollJobCompletion from '/snippets/cloud/poll-job-completion.mdx' diff --git a/development/cloud/openapi.mdx b/development/cloud/openapi.mdx index 64047969c..89ed98627 100644 --- a/development/cloud/openapi.mdx +++ b/development/cloud/openapi.mdx @@ -1,6 +1,7 @@ --- title: "OpenAPI Specification" description: "Machine-readable OpenAPI specification for Comfy Cloud API" +icon: "file-lines" openapi: "/openapi-cloud.yaml" --- diff --git a/development/cloud/overview.mdx b/development/cloud/overview.mdx index e3e5bb511..092b47f6a 100644 --- a/development/cloud/overview.mdx +++ b/development/cloud/overview.mdx @@ -37,11 +37,7 @@ All API requests require an API key passed via the `X-API-Key` header. ### Getting an API Key - - - - Keep your API key secure. Never commit it to version control or share it publicly. - +See [Getting an API Key](/development/api-development/getting-an-api-key) for instructions on creating and managing your Cloud API key. ### Using the API Key @@ -80,7 +76,7 @@ response = requests.get( ### Workflows -ComfyUI workflows are JSON objects describing a graph of nodes. The API accepts workflows in the "API format" (node IDs as keys with class_type, inputs, etc.) as produced by the ComfyUI frontend's "Save (API Format)" option. +ComfyUI workflows are JSON objects describing a graph of nodes. The API accepts workflows in the [API format](/development/api-development/workflow-api-format) (node IDs as keys with class_type, inputs, etc.) as produced by the ComfyUI frontend's "Export Workflow (API)" option. ### Jobs diff --git a/development/comfyui-server/api-examples.mdx b/development/comfyui-server/api-examples.mdx new file mode 100644 index 000000000..8bfd94961 --- /dev/null +++ b/development/comfyui-server/api-examples.mdx @@ -0,0 +1,307 @@ +--- +title: "API Examples" +description: "Three common patterns for calling the ComfyUI Server API" +--- + +This page demonstrates three ways to interact with the ComfyUI Server API, from a simple HTTP submission to a full WebSocket integration with real-time image output. + +All examples use the [default SD1.5 workflow](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples) for illustration. Before using the API, you need to export your workflow in [API format](/development/api-development/workflow-api-format). + + + These examples use Python with the standard library and the `websocket-client` package (`pip install websocket-client`). The underlying API protocol is the same regardless of language — see the [Cloud API Reference](/development/cloud/api-reference) for TypeScript and curl equivalents. + + +--- + +## Method 1: Submit and Forget (HTTP only) + +Source: [`basic_api_example.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/basic_api_example.py) + +The simplest approach: submit a workflow and don't wait for results. Useful for fire-and-forget jobs where you check outputs later. + +```python +"""basic_api_example.py — Submit a workflow via HTTP only.""" + +import json +from urllib import request + +SERVER_ADDRESS = "127.0.0.1:8188" + + +def queue_prompt(prompt): + p = {"prompt": prompt} + data = json.dumps(p).encode("utf-8") + req = request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + request.urlopen(req) + + +if __name__ == "__main__": + # Load a workflow exported in API format + prompt_text = """{ + "3": { + "class_type": "KSampler", + "inputs": { + "cfg": 8, "denoise": 1, + "latent_image": ["5", 0], + "model": ["4", 0], + "negative": ["7", 0], + "positive": ["6", 0], + "sampler_name": "euler", + "scheduler": "normal", + "seed": 8566257, "steps": 20 + } + }, + "4": { + "class_type": "CheckpointLoaderSimple", + "inputs": {"ckpt_name": "v1-5-pruned-emaonly.safetensors"} + }, + "5": { + "class_type": "EmptyLatentImage", + "inputs": {"batch_size": 1, "height": 512, "width": 512} + }, + "6": { + "class_type": "CLIPTextEncode", + "inputs": {"clip": ["4", 1], "text": "masterpiece best quality man"} + }, + "7": { + "class_type": "CLIPTextEncode", + "inputs": {"clip": ["4", 1], "text": "bad hands"} + }, + "8": { + "class_type": "VAEDecode", + "inputs": {"samples": ["3", 0], "vae": ["4", 2]} + }, + "9": { + "class_type": "SaveImage", + "inputs": {"filename_prefix": "ComfyUI", "images": ["8", 0]} + } + }""" + + prompt = json.loads(prompt_text) + # Modify inputs before submitting + prompt["3"]["inputs"]["seed"] = 5 + prompt["6"]["inputs"]["text"] = "masterpiece best quality man" + + queue_prompt(prompt) + print("Prompt submitted successfully.") +``` + + + This method uses the `SaveImage` node, which saves images to disk on the server. To retrieve them, you'd need to follow up with a call to `GET /view?filename=...`. + + +--- + +## Method 2: WebSocket + History (Monitor Completion) + +Source: [`websockets_api_example.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/websockets_api_example.py) + +Use WebSocket to wait for execution to finish, then retrieve outputs via the `/history` endpoint. This is the recommended pattern for most use cases. + +```python +"""websockets_api_example.py — Monitor execution via WebSocket, download via /history.""" + +import websocket # pip install websocket-client +import uuid +import json +import urllib.request +import urllib.parse + +SERVER_ADDRESS = "127.0.0.1:8188" +client_id = str(uuid.uuid4()) + + +def queue_prompt(prompt, prompt_id): + p = {"prompt": prompt, "client_id": client_id, "prompt_id": prompt_id} + data = json.dumps(p).encode("utf-8") + req = urllib.request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + urllib.request.urlopen(req) + + +def get_image(filename, subfolder, folder_type): + params = urllib.parse.urlencode({ + "filename": filename, + "subfolder": subfolder, + "type": folder_type, + }) + with urllib.request.urlopen( + f"http://{SERVER_ADDRESS}/view?{params}" + ) as response: + return response.read() + + +def get_history(prompt_id): + with urllib.request.urlopen( + f"http://{SERVER_ADDRESS}/history/{prompt_id}" + ) as response: + return json.loads(response.read()) + + +def get_images(ws, prompt): + prompt_id = str(uuid.uuid4()) + queue_prompt(prompt, prompt_id) + + while True: + out = ws.recv() + if isinstance(out, str): + message = json.loads(out) + if message["type"] == "executing": + data = message["data"] + if data["node"] is None and data["prompt_id"] == prompt_id: + break # Execution done + # Binary frames are preview images — skip them here + continue + + history = get_history(prompt_id)[prompt_id] + output_images = {} + for node_id in history["outputs"]: + node_output = history["outputs"][node_id] + images_output = [] + if "images" in node_output: + for image in node_output["images"]: + image_data = get_image( + image["filename"], image["subfolder"], image["type"] + ) + images_output.append(image_data) + output_images[node_id] = images_output + return output_images + + +if __name__ == "__main__": + prompt_text = """{ + "3": { ... }, "4": { ... }, "5": { ... }, + "6": { ... }, "7": { ... }, "8": { ... }, + "9": { "class_type": "SaveImage", "inputs": { ... } } + }""" + prompt = json.loads(prompt_text) + prompt["3"]["inputs"]["seed"] = 5 + prompt["6"]["inputs"]["text"] = "masterpiece best quality man" + + ws = websocket.WebSocket() + ws.connect(f"ws://{SERVER_ADDRESS}/ws?clientId={client_id}") + images = get_images(ws, prompt) + ws.close() + + print(f"Got {len(images)} output node(s) with images.") + + # Display the images (requires Pillow): + # for node_id in images: + # for image_data in images[node_id]: + # from PIL import Image + # import io + # img = Image.open(io.BytesIO(image_data)) + # img.show() +``` + + + The WebSocket binary frames contain in-progress preview images during generation. You can decode them for live previews (see the [Server Messages](/development/comfyui-server/comms_messages) page for the binary format). + + +--- + +## Method 3: WebSocket with SaveImageWebsocket (Real-time Images) + +Source: [`websockets_api_example_ws_images.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/websockets_api_example_ws_images.py) + +For scenarios where you don't want images saved to disk, use the `SaveImageWebsocket` node. Images are delivered directly via WebSocket binary frames. + +```python +"""websockets_api_example_ws_images.py — Receive images directly via WebSocket.""" + +import websocket # pip install websocket-client +import uuid +import json +import urllib.request +import urllib.parse + +SERVER_ADDRESS = "127.0.0.1:8188" +client_id = str(uuid.uuid4()) + + +def queue_prompt(prompt): + p = {"prompt": prompt, "client_id": client_id} + data = json.dumps(p).encode("utf-8") + req = urllib.request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + return json.loads(urllib.request.urlopen(req).read()) + + +def get_images(ws, prompt): + prompt_id = queue_prompt(prompt)["prompt_id"] + output_images = {} + current_node = "" + + while True: + out = ws.recv() + if isinstance(out, str): + message = json.loads(out) + if message["type"] == "executing": + data = message["data"] + if data["prompt_id"] == prompt_id: + if data["node"] is None: + break # Execution done + current_node = data["node"] + else: + # Binary frame — image data from SaveImageWebsocket + if current_node == "save_image_websocket_node": + images_output = output_images.get(current_node, []) + # The first 8 bytes are type/meta, rest is image data + images_output.append(out[8:]) + output_images[current_node] = images_output + + return output_images + + +if __name__ == "__main__": + prompt_text = """{ + "3": { "class_type": "KSampler", "inputs": { ... } }, + ... + "save_image_websocket_node": { + "class_type": "SaveImageWebsocket", + "inputs": {"images": ["8", 0]} + } + }""" + prompt = json.loads(prompt_text) + prompt["3"]["inputs"]["seed"] = 5 + + ws = websocket.WebSocket() + ws.connect(f"ws://{SERVER_ADDRESS}/ws?clientId={client_id}") + images = get_images(ws, prompt) + ws.close() + + print(f"Received {len(images)} image(s) via WebSocket.") + + # Display (requires Pillow): + # for image_data in images.get("save_image_websocket_node", []): + # from PIL import Image + # import io + # img = Image.open(io.BytesIO(image_data)) + # img.show() +``` + + + The workflow must use a node with `class_type: "SaveImageWebsocket"` (a built-in node) instead of the regular `SaveImage` node. + + +--- + +## Which Method Should I Use? + + + + **Fire and forget.** Use when you don't need immediate output, or when retrieving results later is acceptable. + + + **Recommended.** Wait for completion, then download outputs. Best balance of simplicity and reliability. + + + **Real-time images.** Best for interactive apps where you want images delivered without disk writes. + + + +For the full API reference (endpoints, payload formats, error handling), see the [Server Routes](/development/comfyui-server/comms_routes) and [Server Messages](/development/comfyui-server/comms_messages) pages. diff --git a/development/comfyui-server/api-key-integration.mdx b/development/comfyui-server/api-key-integration.mdx index d7f3efa44..6a6e970f5 100644 --- a/development/comfyui-server/api-key-integration.mdx +++ b/development/comfyui-server/api-key-integration.mdx @@ -2,6 +2,7 @@ title: 'ComfyUI Account API Key Integration' description: 'This article explains how to use ComfyUI Account API Key to call paid Partner Nodes in headless mode' sidebarTitle: 'Partner Node API Integration' +icon: 'puzzle-piece' --- Starting from [PR #8041](https://github.com/Comfy-Org/ComfyUI/pull/8041), ComfyUI supports directly using built-in paid Partner Nodes through your ComfyUI Account API Key, without requiring a specific frontend interface (you can even run without a frontend). @@ -27,9 +28,7 @@ Using your ComfyUI Account API Key to call paid Partner Nodes requires: To use your ComfyUI Account API Key to call paid Partner Nodes, you need to first register an account on [ComfyUI Platform](https://platform.comfy.org/login) and [create an API key](/development/api-development/getting-an-api-key) - -Please refer to the User Interface section to learn how to login with API Key - + You need to ensure your ComfyUI account has sufficient credits to test the corresponding features. diff --git a/development/comfyui-server/comms_messages.mdx b/development/comfyui-server/comms_messages.mdx index fd04a86c5..b1d214f5a 100644 --- a/development/comfyui-server/comms_messages.mdx +++ b/development/comfyui-server/comms_messages.mdx @@ -1,5 +1,6 @@ --- title: "Messages" +icon: "comment" --- ## Messages diff --git a/development/comfyui-server/comms_overview.mdx b/development/comfyui-server/comms_overview.mdx index a847a4272..3229accd7 100644 --- a/development/comfyui-server/comms_overview.mdx +++ b/development/comfyui-server/comms_overview.mdx @@ -1,18 +1,70 @@ --- title: "Server Overview" +description: "Run ComfyUI as a server and interact with it programmatically via REST and WebSocket APIs" --- -## Overview +ComfyUI runs as an HTTP server on your machine by default. You can call it programmatically to submit workflows, upload files, download outputs, and monitor progress — all without opening the browser. + +## Starting the Server + +When you launch ComfyUI, it automatically starts an HTTP server at `http://127.0.0.1:8188`. + +To run ComfyUI as a headless server (no browser): + + +```bash +# Run without opening the browser +python main.py --headless +``` + +```bash +# Specify a custom port +python main.py --port 8288 +``` + +```bash +# Listen on all network interfaces (for remote access) +python main.py --listen 0.0.0.0 +``` + + + + For a full list of startup flags, run `python main.py --help` or see the [install guide](/installation/manual_install#basic-usage). + + +## Key Pages in This Section + + + + Available HTTP endpoints for submitting workflows, uploading files, and querying status. + + + Code examples for calling the API: HTTP-only, WebSocket + History, and SaveImageWebsocket. + + + WebSocket message types the server sends to the client during execution. + + + Advanced: invert execution for custom control flows. + + + +## Using Partner Nodes + +If your workflow contains paid Partner Nodes, you can include your API key in the payload. See the [Partner Node API Integration](/development/comfyui-server/api-key-integration) guide for details. + +--- + +## How the Server Works The Comfy server runs on top of the [aiohttp framework](https://docs.aiohttp.org/), which in turn uses [asyncio](https://pypi.org/project/asyncio/). -Messages from the server to the client are sent by socket messages through the `send_sync` method of the server, -which is an instance of `PromptServer` (defined in `server.py`). They are processed -by a socket event listener registered in `api.js`. See [messages](/development/comfyui-server/comms_messages). +Messages from the server to the client are sent by socket messages through the `send_sync` method of the server, which is an instance of `PromptServer` (defined in `server.py`). They are processed by a socket event listener registered in `api.js`. See [messages](/development/comfyui-server/comms_messages). -Messages from the client to the server are sent by the `api.fetchApi()` method defined in `api.js`, -and are handled by http routes defined by the server. See [routes](/development/comfyui-server/comms_routes). +Messages from the client to the server are sent by the `api.fetchApi()` method defined in `api.js`, and are handled by HTTP routes defined by the server. See [routes](/development/comfyui-server/comms_routes). -The client submits the whole workflow (widget values and all) when you queue a request. -The server does not receive any changes you make after you send a request to the queue. -If you want to modify server behavior during execution, you'll need routes. + + The client submits the whole workflow (widget values and all) when you queue a request. + The server does not receive any changes you make after you send a request to the queue. + If you want to modify server behavior during execution, you'll need routes. + diff --git a/development/comfyui-server/comms_routes.mdx b/development/comfyui-server/comms_routes.mdx index 92b8a1e41..ba2122665 100644 --- a/development/comfyui-server/comms_routes.mdx +++ b/development/comfyui-server/comms_routes.mdx @@ -1,5 +1,6 @@ --- title: "Routes" +icon: "route" --- ## Routes diff --git a/development/comfyui-server/execution_model_inversion_guide.mdx b/development/comfyui-server/execution_model_inversion_guide.mdx index 6378df658..3289c2bcf 100644 --- a/development/comfyui-server/execution_model_inversion_guide.mdx +++ b/development/comfyui-server/execution_model_inversion_guide.mdx @@ -1,5 +1,6 @@ --- title: "Execution Model Inversion Guide" +icon: "code-branch" --- [PR #2666](https://github.com/Comfy-Org/ComfyUI/pull/2666) inverts the execution model from a back-to-front recursive model to a front-to-back topological sort. While most custom nodes should continue to "just work", this page is intended to serve as a guide for custom node creators to the things that *could* break. diff --git a/development/overview.mdx b/development/overview.mdx index c82010b48..7a2a83ade 100644 --- a/development/overview.mdx +++ b/development/overview.mdx @@ -9,11 +9,11 @@ ComfyUI is a modular GenAI inference engine that can be run as a server, accesse Run ComfyUI in your own environment and expose it as an API endpoint. Learn about the WebSocket message protocol, available routes, and execution modes. - - Get started with the local server setup, message types, route handling, and execution model inversion. + + Run ComfyUI as a server on your own machine. Start, configure, and call it via REST and WebSocket APIs. -See also: [Messages & Routes](/development/comfyui-server/comms_messages) · [Execution Model Inversion](/development/comfyui-server/execution_model_inversion_guide) · [Partner Node API Integration](/development/comfyui-server/api-key-integration) +See also: [API Examples](/development/comfyui-server/api-examples) · [Partner Node API Integration](/development/comfyui-server/api-key-integration) ## Cloud API @@ -23,7 +23,7 @@ Run workflows programmatically on Comfy Cloud without managing your own hardware Learn how to authenticate, submit jobs, check status, and download results from Comfy Cloud. -See also: [API Reference](/development/cloud/api-reference) · [OpenAPI Specification](/development/cloud/openapi) · [Getting an API Key](/development/api-development/getting-an-api-key) +See also: [API Reference](/development/cloud/api-reference) · [OpenAPI Specification](/development/cloud/openapi) · [Getting an API Key](/development/api-development/getting-an-api-key) · [APIs Overview](/development/api-development/overview) ## Agent Tools / MCP diff --git a/docs.json b/docs.json index 5b46f867c..a30c5bcb5 100644 --- a/docs.json +++ b/docs.json @@ -2257,30 +2257,35 @@ "tab": "Development", "pages": [ "development/overview", + { - "group": "ComfyUI Server", - "icon": "code", + "group": "ComfyUI APIs", + "icon": "computer", "pages": [ - "development/comfyui-server/comms_overview", - "development/comfyui-server/comms_messages", - "development/comfyui-server/comms_routes", - "development/comfyui-server/execution_model_inversion_guide" - ] - }, - { - "group": "Cloud & Partner APIs", - "icon": "cloud", - "pages": [ - "development/api-development/getting-an-api-key", - "development/comfyui-server/api-key-integration", + "development/api-development/overview", { "group": "Cloud API", + "icon": "cloud", "pages": [ "development/cloud/overview", "development/cloud/api-reference", "development/cloud/openapi" ] - } + }, + { + "group": "ComfyUI Server API", + "icon": "server", + "pages": [ + "development/comfyui-server/comms_overview", + "development/comfyui-server/comms_routes", + "development/comfyui-server/api-examples", + "development/comfyui-server/comms_messages", + "development/comfyui-server/execution_model_inversion_guide" + ] + }, + "development/comfyui-server/api-key-integration", + "development/api-development/workflow-api-format", + "development/api-development/getting-an-api-key" ] }, { @@ -4696,30 +4701,35 @@ "tab": "开发", "pages": [ "zh/development/overview", + { - "group": "ComfyUI Server", - "icon": "code", - "pages": [ - "zh/development/comfyui-server/comms_overview", - "zh/development/comfyui-server/comms_messages", - "zh/development/comfyui-server/comms_routes", - "zh/development/comfyui-server/execution_model_inversion_guide" - ] - }, - { - "group": "Cloud & Partner APIs", - "icon": "cloud", + "group": "ComfyUI APIs", + "icon": "computer", "pages": [ - "zh/development/api-development/getting-an-api-key", - "zh/development/comfyui-server/api-key-integration", + "zh/development/api-development/overview", { "group": "Cloud API", + "icon": "cloud", "pages": [ "zh/development/cloud/overview", "zh/development/cloud/api-reference", "zh/development/cloud/openapi" ] - } + }, + { + "group": "ComfyUI Server API", + "icon": "server", + "pages": [ + "zh/development/comfyui-server/comms_overview", + "zh/development/comfyui-server/comms_routes", + "zh/development/comfyui-server/api-examples", + "zh/development/comfyui-server/comms_messages", + "zh/development/comfyui-server/execution_model_inversion_guide" + ] + }, + "zh/development/comfyui-server/api-key-integration", + "zh/development/api-development/workflow-api-format", + "zh/development/api-development/getting-an-api-key" ] }, { @@ -7135,30 +7145,35 @@ "tab": "開発", "pages": [ "ja/development/overview", + { - "group": "ComfyUI Server", - "icon": "code", - "pages": [ - "ja/development/comfyui-server/comms_overview", - "ja/development/comfyui-server/comms_messages", - "ja/development/comfyui-server/comms_routes", - "ja/development/comfyui-server/execution_model_inversion_guide" - ] - }, - { - "group": "Cloud & Partner APIs", - "icon": "cloud", + "group": "ComfyUI APIs", + "icon": "computer", "pages": [ - "ja/development/api-development/getting-an-api-key", - "ja/development/comfyui-server/api-key-integration", + "ja/development/api-development/overview", { "group": "Cloud API", + "icon": "cloud", "pages": [ "ja/development/cloud/overview", "ja/development/cloud/api-reference", "ja/development/cloud/openapi" ] - } + }, + { + "group": "ComfyUI Server API", + "icon": "server", + "pages": [ + "ja/development/comfyui-server/comms_overview", + "ja/development/comfyui-server/comms_routes", + "ja/development/comfyui-server/api-examples", + "ja/development/comfyui-server/comms_messages", + "ja/development/comfyui-server/execution_model_inversion_guide" + ] + }, + "ja/development/comfyui-server/api-key-integration", + "ja/development/api-development/workflow-api-format", + "ja/development/api-development/getting-an-api-key" ] }, { diff --git a/images/development/export_workflow_api_format.png b/images/development/export_workflow_api_format.png new file mode 100644 index 000000000..1d7fff09d Binary files /dev/null and b/images/development/export_workflow_api_format.png differ diff --git a/ja/development/api-development/getting-an-api-key.mdx b/ja/development/api-development/getting-an-api-key.mdx index 3287b6402..8194e8dd2 100644 --- a/ja/development/api-development/getting-an-api-key.mdx +++ b/ja/development/api-development/getting-an-api-key.mdx @@ -1,6 +1,7 @@ --- title: 'API キーの取得' description: 'Cloud API、Partner Node などにアクセスするための Comfy Platform API キーの作成と管理方法を学びます。' +icon: 'key' --- import GetApiKey from '/snippets/ja/get-api-key.mdx' diff --git a/ja/development/api-development/overview.mdx b/ja/development/api-development/overview.mdx new file mode 100644 index 000000000..66763de1c --- /dev/null +++ b/ja/development/api-development/overview.mdx @@ -0,0 +1,46 @@ +--- +title: "API 概要" +description: "ComfyUI をプログラムから操作するための様々なAPIの概要" +icon: "list" +--- + +ComfyUI には、ワークフローを実行する場所や管理したいインフラストラクチャに応じて、複数の API オプションがあります。このページは適切な方法を選ぶのに役立ちます。 + +--- + +## どの API を使うべきか？ + +| | Cloud API | ComfyUI Server API | +|---|---|---| +| **実行環境** | Comfy Cloud（マネージド GPU） | 自分のマシン | +| **GPU 管理** | 不要 | 自分で管理 | +| **モデル** | クラウドにプリインストール | 自分でダウンロード・管理 | +| **認証** | `X-API-Key` ヘッダー | 不要（ローカル）または API Key（Partner Nodes） | +| **ベースURL** | `https://cloud.comfy.org` | サーバーURL（例：`http://localhost:8188`）| +| **プロトコル** | REST + WebSocket | REST + WebSocket | +| **料金** | サブスクリプション制 | 無料（自分の計算リソース）| +| **用途** | 迅速な統合、インフラ不要 | 完全制御、カスタムハードウェア・モデル | + +両 API は同じワークフロー形式（[API 形式](/ja/development/api-development/workflow-api-format)）を使用するため、ローカルで開発・テストしてからクラウドに移行しても変更は不要です。 + +--- + +## クイックスタート + + + + Comfy のマネージドインフラ上でワークフローを実行。GPU 設定は不要。 + + + 自分のマシンで ComfyUI をサーバーとして実行し、API 経由で呼び出し。 + + + ヘッドレスまたは API 駆動のワークフローで Partner Nodes を利用。 + + + +--- + +## 前提条件 + +- API Key（[API Key の取得](/ja/development/api-development/getting-an-api-key)を参照） diff --git a/ja/development/api-development/workflow-api-format.mdx b/ja/development/api-development/workflow-api-format.mdx new file mode 100644 index 000000000..b9dfd2a4c --- /dev/null +++ b/ja/development/api-development/workflow-api-format.mdx @@ -0,0 +1,170 @@ +--- +title: "ワークフロー API 形式" +description: "ComfyUI ワークフローの API 形式とそのエクスポート方法" +icon: "file-code" +--- + +ComfyUI ワークフローは、ノードのグラフを記述する JSON オブジェクトです。Cloud API や自身のサーバーを通じてプログラムから ComfyUI を呼び出す場合、ワークフローは**API 形式**で送信する必要があります。これはブラウザで使用される通常の保存形式とは異なる専用の JSON 構造です。 + +このページでは、両者の違いとワークフローを正しくエクスポートする方法を説明します。 + +--- + +## 保存形式 vs API 形式 + +ComfyUI フロントエンドは 2 つの形式でワークフローを保存できます： + +| | 保存形式 | API 形式 | +|---|---|---| +| **メニュー** | `File → Save` または `Ctrl+S` | `File → Export Workflow (API)` | +| **ファイル拡張子** | `.json` | `.json` | +| **ノードキー** | ノードタイトルまたはラベル | 数値ノード ID | +| **ウィジェット値** | 含む | 含む | +| **位置/レイアウトデータ** | 含む (x, y, width) | **含まない** | +| **色/グループ** | 含む | **含まない** | +| **用途** | フロントエンドで再読み込み | API 送信用 | +| **UI に読み込み可能か** | 可 | 可（ただしレイアウトなし）| + +重要な違い：**API 形式は UI メタデータを省略**します（位置、色、グループ、ノードサイズ）。これらはフロントエンドでの視覚的編集にのみ必要なためです。これにより JSON がより小さく、プログラムでの使用に適した形になります。 + +--- + +## エクスポート方法 + +ComfyUI フロントエンドでワークフローを開き、`File → Export Workflow (API)` を選択します： + + + API 形式でワークフローを保存 + + +これにより、API 関連データのみを含む `.json` ファイルがダウンロードされます： + +```json +{ + "3": { + "inputs": { + "seed": 156680208700286, + "steps": 20, + "cfg": 8, + "sampler_name": "euler", + "scheduler": "normal", + "denoise": 1, + "model": [ + "4", + 0 + ], + "positive": [ + "6", + 0 + ], + "negative": [ + "7", + 0 + ], + "latent_image": [ + "5", + 0 + ] + }, + "class_type": "KSampler", + "_meta": { + "title": "KSampler" + } + }, + "4": { + "inputs": { + "ckpt_name": "v1-5-pruned-emaonly-fp16.safetensors" + }, + "class_type": "CheckpointLoaderSimple", + "_meta": { + "title": "Load Checkpoint" + } + }, + "5": { + "inputs": { + "width": 512, + "height": 512, + "batch_size": 1 + }, + "class_type": "EmptyLatentImage", + "_meta": { + "title": "Empty Latent Image" + } + }, + "6": { + "inputs": { + "text": "beautiful scenery nature glass bottle landscape, , purple galaxy bottle,", + "clip": [ + "4", + 1 + ] + }, + "class_type": "CLIPTextEncode", + "_meta": { + "title": "CLIP Text Encode (Prompt)" + } + }, + "7": { + "inputs": { + "text": "text, watermark", + "clip": [ + "4", + 1 + ] + }, + "class_type": "CLIPTextEncode", + "_meta": { + "title": "CLIP Text Encode (Prompt)" + } + }, + "8": { + "inputs": { + "samples": [ + "3", + 0 + ], + "vae": [ + "4", + 2 + ] + }, + "class_type": "VAEDecode", + "_meta": { + "title": "VAE Decode" + } + }, + "9": { + "inputs": { + "filename_prefix": "ComfyUI", + "images": [ + "8", + 0 + ] + }, + "class_type": "SaveImage", + "_meta": { + "title": "Save Image" + } + } +} +``` + +--- + +## 形式の変換 + +保存形式のワークフローを API 形式に変換する最も簡単な方法： + +1. フロントエンドで `File → Load` から `.json` ファイルを開く +2. `File → Export Workflow (API)` で再エクスポート + +自動化が必要な場合は、各ノードの `x`、`y`、`width` フィールドを削除し、ルート JSON から `groups` と `extra` セクションを取り除くスクリプトを作成できます。 + +--- + +## 関連ページ + +- [API 概要](/ja/development/api-development/overview) — Cloud と Server API の比較 +- [Cloud API 概要](/ja/development/cloud/overview) — Comfy Cloud に API 形式のワークフローを送信 +- [API 例](/ja/development/comfyui-server/api-examples) — API 形式ワークフローの実例 +- [API Key の取得](/ja/development/api-development/getting-an-api-key) — Cloud API と Partner Nodes に必要 diff --git a/ja/development/cloud/api-reference.mdx b/ja/development/cloud/api-reference.mdx index 6180c4401..7ea11a63a 100644 --- a/ja/development/cloud/api-reference.mdx +++ b/ja/development/cloud/api-reference.mdx @@ -1,6 +1,7 @@ --- title: "Cloud API リファレンス" description: "Comfy Cloud の完全な API リファレンスとコード例" +icon: "book-open" translationSourceHash: ef54c171 translationFrom: development/cloud/api-reference.mdx, zh/development/cloud/api-reference.mdx translationMismatches: diff --git a/ja/development/cloud/openapi.mdx b/ja/development/cloud/openapi.mdx index db8e331f0..eae92b9d0 100644 --- a/ja/development/cloud/openapi.mdx +++ b/ja/development/cloud/openapi.mdx @@ -1,6 +1,7 @@ --- title: "OpenAPI 仕様" description: "Comfy Cloud API の機械可読な OpenAPI 仕様" +icon: "file-lines" openapi: "/openapi-cloud.yaml" translationSourceHash: 04c13223 translationFrom: development/cloud/openapi.mdx, zh/development/cloud/openapi.mdx diff --git a/ja/development/cloud/overview.mdx b/ja/development/cloud/overview.mdx index 34f418bd0..1ded1afb0 100644 --- a/ja/development/cloud/overview.mdx +++ b/ja/development/cloud/overview.mdx @@ -39,11 +39,7 @@ https://cloud.comfy.org ### API キーの取得 - - - - API キーは安全に保管してください。バージョン管理システムにコミットしたり、公開で共有したりしないでください。 - +API キーの作成と管理方法については、[API キーの取得](/ja/development/api-development/getting-an-api-key)を参照してください。 ### API キーの使用 @@ -82,7 +78,7 @@ response = requests.get( ### ワークフロー -ComfyUI ワークフローは、ノードのグラフを記述する JSON オブジェクトです。API は「API 形式」のワークフローを受け付けます（ノード ID をキーとし、class_type、inputs などを含む）。この形式は、ComfyUI フロントエンドの「Save (API Format)」オプションによって生成されます。 +ComfyUI ワークフローは、ノードのグラフを記述する JSON オブジェクトです。API は [API 形式](/ja/development/api-development/workflow-api-format) のワークフローを受け付けます（ノード ID をキーとし、class_type、inputs などを含む）。この形式は、ComfyUI フロントエンドの「Export Workflow (API)」オプションによって生成されます。 ### ジョブ diff --git a/ja/development/comfyui-server/api-examples.mdx b/ja/development/comfyui-server/api-examples.mdx new file mode 100644 index 000000000..f354eb413 --- /dev/null +++ b/ja/development/comfyui-server/api-examples.mdx @@ -0,0 +1,254 @@ +--- +title: "API 例" +description: "ComfyUI Server API を呼び出す3つのパターン" +--- + +このページでは、シンプルな HTTP 送信から WebSocket を使用したリアルタイム画像出力まで、ComfyUI Server API との3つの対話方法を紹介します。 + +すべての例は[デフォルトの SD1.5 ワークフロー](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples)を使用しています。API を使用する前に、ワークフローを [API 形式](/ja/development/api-development/workflow-api-format) でエクスポートする必要があります。 + + + これらの例は Python 標準ライブラリと `websocket-client` パッケージ（`pip install websocket-client`）を使用しています。API プロトコルは言語に依存しません — TypeScript と curl 版については [Cloud API リファレンス](/ja/development/cloud/api-reference)を参照してください。 + + +--- + +## 方法1：送信して忘れる（HTTP のみ） + +ソース：[`basic_api_example.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/basic_api_example.py) + +最もシンプルな方法：ワークフローを送信し、結果を待ちません。後で出力を確認するような「送りっぱなし」のジョブに適しています。 + +```python +"""basic_api_example.py — HTTP のみでワークフローを送信。""" + +import json +from urllib import request + +SERVER_ADDRESS = "127.0.0.1:8188" + + +def queue_prompt(prompt): + p = {"prompt": prompt} + data = json.dumps(p).encode("utf-8") + req = request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + request.urlopen(req) + + +if __name__ == "__main__": + # API 形式でエクスポートされたワークフローを読み込み + prompt_text = """{ + "3": { + "class_type": "KSampler", + "inputs": { + "cfg": 8, "denoise": 1, + "latent_image": ["5", 0], + "model": ["4", 0], + "negative": ["7", 0], + "positive": ["6", 0], + "sampler_name": "euler", + "scheduler": "normal", + "seed": 8566257, "steps": 20 + } + }, + "4": { + "class_type": "CheckpointLoaderSimple", + "inputs": {"ckpt_name": "v1-5-pruned-emaonly.safetensors"} + }, + "5": { + "class_type": "EmptyLatentImage", + "inputs": {"batch_size": 1, "height": 512, "width": 512} + }, + "6": { + "class_type": "CLIPTextEncode", + "inputs": {"clip": ["4", 1], "text": "masterpiece best quality man"} + }, + "7": { + "class_type": "CLIPTextEncode", + "inputs": {"clip": ["4", 1], "text": "bad hands"} + }, + "8": { + "class_type": "VAEDecode", + "inputs": {"samples": ["3", 0], "vae": ["4", 2]} + }, + "9": { + "class_type": "SaveImage", + "inputs": {"filename_prefix": "ComfyUI", "images": ["8", 0]} + } + }""" + + prompt = json.loads(prompt_text) + # 送信前に入力を変更 + prompt["3"]["inputs"]["seed"] = 5 + prompt["6"]["inputs"]["text"] = "masterpiece best quality man" + + queue_prompt(prompt) + print("Prompt submitted successfully.") +``` + + + この方法は `SaveImage` ノードを使用するため、画像はサーバーのディスクに保存されます。画像を取得するには `GET /view?filename=...` を呼び出す必要があります。 + + +--- + +## 方法2：WebSocket + History（完了を監視） + +ソース：[`websockets_api_example.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/websockets_api_example.py) + +WebSocket で実行完了を待ち、`/history` エンドポイントから結果を取得します。ほとんどのユースケースで推奨されるパターンです。 + +```python +"""websockets_api_example.py — WebSocket で実行を監視、/history からダウンロード。""" + +import websocket # pip install websocket-client +import uuid +import json +import urllib.request +import urllib.parse + +SERVER_ADDRESS = "127.0.0.1:8188" +client_id = str(uuid.uuid4()) + + +def queue_prompt(prompt, prompt_id): + p = {"prompt": prompt, "client_id": client_id, "prompt_id": prompt_id} + data = json.dumps(p).encode("utf-8") + req = urllib.request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + urllib.request.urlopen(req) + + +def get_image(filename, subfolder, folder_type): + params = urllib.parse.urlencode({ + "filename": filename, + "subfolder": subfolder, + "type": folder_type, + }) + with urllib.request.urlopen( + f"http://{SERVER_ADDRESS}/view?{params}" + ) as response: + return response.read() + + +def get_history(prompt_id): + with urllib.request.urlopen( + f"http://{SERVER_ADDRESS}/history/{prompt_id}" + ) as response: + return json.loads(response.read()) + + +def get_images(ws, prompt): + prompt_id = str(uuid.uuid4()) + queue_prompt(prompt, prompt_id) + + while True: + out = ws.recv() + if isinstance(out, str): + message = json.loads(out) + if message["type"] == "executing": + data = message["data"] + if data["node"] is None and data["prompt_id"] == prompt_id: + break # 実行完了 + # バイナリフレームはプレビュー画像 — ここではスキップ + continue + + history = get_history(prompt_id)[prompt_id] + output_images = {} + for node_id in history["outputs"]: + node_output = history["outputs"][node_id] + images_output = [] + if "images" in node_output: + for image in node_output["images"]: + image_data = get_image( + image["filename"], image["subfolder"], image["type"] + ) + images_output.append(image_data) + output_images[node_id] = images_output + return output_images +``` + + + WebSocket のバイナリフレームには生成途中のプレビュー画像が含まれています。ライブプレビュー用にデコードできます（バイナリ形式の詳細は[サーバーメッセージ](/ja/development/comfyui-server/comms_messages)ページを参照）。 + + +--- + +## 方法3：WebSocket + SaveImageWebsocket（リアルタイム画像） + +ソース：[`websockets_api_example_ws_images.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/websockets_api_example_ws_images.py) + +画像をディスクに保存せずに受け取りたい場合は、`SaveImageWebsocket` ノードを使用します。画像は WebSocket のバイナリフレームで直接配信されます。 + +```python +"""websockets_api_example_ws_images.py — WebSocket 経由で画像を直接受信。""" + +import websocket # pip install websocket-client +import uuid +import json +import urllib.request +import urllib.parse + +SERVER_ADDRESS = "127.0.0.1:8188" +client_id = str(uuid.uuid4()) + + +def queue_prompt(prompt): + p = {"prompt": prompt, "client_id": client_id} + data = json.dumps(p).encode("utf-8") + req = urllib.request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + return json.loads(urllib.request.urlopen(req).read()) + + +def get_images(ws, prompt): + prompt_id = queue_prompt(prompt)["prompt_id"] + output_images = {} + current_node = "" + + while True: + out = ws.recv() + if isinstance(out, str): + message = json.loads(out) + if message["type"] == "executing": + data = message["data"] + if data["prompt_id"] == prompt_id: + if data["node"] is None: + break # 実行完了 + current_node = data["node"] + else: + # バイナリフレーム — SaveImageWebsocket の画像データ + if current_node == "save_image_websocket_node": + images_output = output_images.get(current_node, []) + # 先頭8バイトはタイプ/メタデータ、残りが画像データ + images_output.append(out[8:]) + output_images[current_node] = images_output + + return output_images +``` + + + ワークフローは通常の `SaveImage` ノードの代わりに `class_type: "SaveImageWebsocket"`（組み込みノード）を使用する必要があります。 + + +--- + +## どの方法を選ぶべきか？ + + + + **送って忘れる。** 即時の出力が必要ない場合に。 + + + **推奨。** 完了を待ち、結果をダウンロード。シンプルさと信頼性の最適なバランス。 + + + **リアルタイム画像。** ディスク書き込みなしで画像を受け取りたいインタラクティブなアプリに。 + + + +完全な API リファレンス（エンドポイント、ペイロード形式、エラー処理）については、[サーバールート](/ja/development/comfyui-server/comms_routes)および[サーバーメッセージ](/ja/development/comfyui-server/comms_messages)ページを参照してください。 diff --git a/ja/development/comfyui-server/api-key-integration.mdx b/ja/development/comfyui-server/api-key-integration.mdx index 1fae778a3..be434c88c 100644 --- a/ja/development/comfyui-server/api-key-integration.mdx +++ b/ja/development/comfyui-server/api-key-integration.mdx @@ -2,6 +2,7 @@ title: 'ComfyUI アカウント API キー統合' description: 'この記事では、ヘッドレスモードで有料 API ノードを呼び出すために ComfyUI アカウント API キーを使用する方法について説明します' sidebarTitle: 'Partner Node API 統合' +icon: 'puzzle-piece' translationSourceHash: 6d4591f9 translationFrom: development/comfyui-server/api-key-integration.mdx, zh/development/comfyui-server/api-key-integration.mdx --- diff --git a/ja/development/comfyui-server/comms_messages.mdx b/ja/development/comfyui-server/comms_messages.mdx index 435ef0dad..eb4092b5f 100644 --- a/ja/development/comfyui-server/comms_messages.mdx +++ b/ja/development/comfyui-server/comms_messages.mdx @@ -1,5 +1,6 @@ --- title: "メッセージ" +icon: "comment" translationSourceHash: 7229c28c translationFrom: development/comfyui-server/comms_messages.mdx, zh/development/comfyui-server/comms_messages.mdx --- diff --git a/ja/development/comfyui-server/comms_overview.mdx b/ja/development/comfyui-server/comms_overview.mdx index 62e5625c0..3707b9ad7 100644 --- a/ja/development/comfyui-server/comms_overview.mdx +++ b/ja/development/comfyui-server/comms_overview.mdx @@ -1,15 +1,68 @@ --- title: "サーバー概要" -translationSourceHash: eb8a8f9c -translationFrom: development/comfyui-server/comms_overview.mdx, zh/development/comfyui-server/comms_overview.mdx +description: "ComfyUI をサーバーとして実行し、REST および WebSocket API でプログラムから操作" --- -## 概要 +ComfyUI はデフォルトで HTTP サーバーとしてローカルで実行されます。ブラウザを開かずに、プログラムからワークフローの送信、ファイルのアップロード、出力のダウンロード、進捗の監視が可能です。 + +## サーバーの起動 + +ComfyUI を起動すると、自動的に HTTP サーバーが `http://127.0.0.1:8188` で起動します。 + +ヘッドレスモード（ブラウザを開かずに）で実行： + + +```bash +# ブラウザを開かずに実行 +python main.py --headless +``` + +```bash +# カスタムポートを指定 +python main.py --port 8288 +``` + +```bash +# 全ネットワークインターフェースで待受（リモートアクセス用） +python main.py --listen 0.0.0.0 +``` + + + + 全起動オプションの一覧は `python main.py --help` を実行してください。[インストールガイド](/ja/installation/manual_install#basic-usage)も参照。 + + +## このセクションの主要ページ + + + + ワークフロー送信、ファイルアップロード、ステータス確認用の HTTP エンドポイント。 + + + API 呼び出しのコード例：HTTP のみ、WebSocket + History、SaveImageWebsocket。 + + + 実行中にサーバーからクライアントに送信される WebSocket メッセージタイプ。 + + + 上級：カスタム制御フローのための実行逆転。 + + + +## Partner Nodes の使用 + +ワークフローに有料 Partner Nodes が含まれている場合、ペイロードに API Key を含めることができます。詳細は [Partner Node API 統合](/ja/development/comfyui-server/api-key-integration) ガイドを参照してください。 + +--- + +## サーバーの仕組み Comfy サーバーは [aiohttp フレームワーク](https://docs.aiohttp.org/) 上で動作しており、このフレームワークはさらに [asyncio](https://pypi.org/project/asyncio/) を使用しています。 -サーバーからクライアントへのメッセージは、サーバーの `send_sync` メソッドを通じてソケットメッセージとして送信されます。このサーバーは `server.py` で定義された `PromptServer` のインスタンスです。これらのメッセージは `api.js` に登録されたソケットイベントリスナーによって処理されます。詳細は [メッセージ](/development/comfyui-server/comms_messages) を参照してください。 +サーバーからクライアントへのメッセージは、`send_sync` メソッド（`server.py` で定義された `PromptServer` のインスタンス）を通じてソケットメッセージとして送信されます。これらのメッセージは `api.js` に登録されたソケットイベントリスナーによって処理されます。詳細は[メッセージ](/ja/development/comfyui-server/comms_messages)を参照。 -クライアントからサーバーへのメッセージは、`api.js` で定義された `api.fetchApi()` メソッドによって送信され、サーバーによって定義された HTTP ルートによって処理されます。詳細は [ルート](/development/comfyui-server/comms_routes) を参照してください。 +クライアントからサーバーへのメッセージは、`api.js` で定義された `api.fetchApi()` メソッドによって送信され、サーバーによって定義された HTTP ルートによって処理されます。詳細は[ルート](/ja/development/comfyui-server/comms_routes)を参照。 -リクエストをキューに追加すると、クライアントはワークフロー全体（ウィジェット値などすべて）を送信します。キューにリクエストを送信した後に変更を加えても、サーバーはその変更を受け取りません。実行中にサーバーの動作を変更したい場合は、ルートを使用する必要があります。 \ No newline at end of file + + リクエストをキューに追加すると、クライアントはワークフロー全体（ウィジェット値などすべて）を送信します。キューに送信した後に加えた変更はサーバーに反映されません。実行中にサーバーの動作を変更したい場合は、ルートを使用してください。 + diff --git a/ja/development/comfyui-server/comms_routes.mdx b/ja/development/comfyui-server/comms_routes.mdx index b24308155..c34c21cb4 100644 --- a/ja/development/comfyui-server/comms_routes.mdx +++ b/ja/development/comfyui-server/comms_routes.mdx @@ -1,5 +1,6 @@ --- title: "ルート" +icon: "route" translationSourceHash: 5064650f translationFrom: development/comfyui-server/comms_routes.mdx, zh/development/comfyui-server/comms_routes.mdx --- diff --git a/ja/development/comfyui-server/execution_model_inversion_guide.mdx b/ja/development/comfyui-server/execution_model_inversion_guide.mdx index b4ff08208..3e89d8c1a 100644 --- a/ja/development/comfyui-server/execution_model_inversion_guide.mdx +++ b/ja/development/comfyui-server/execution_model_inversion_guide.mdx @@ -1,5 +1,6 @@ --- title: "実行モデル反転ガイド" +icon: "code-branch" translationSourceHash: dfad1b9a translationFrom: development/comfyui-server/execution_model_inversion_guide.mdx, zh/development/comfyui-server/execution_model_inversion_guide.mdx --- diff --git a/zh/development/api-development/getting-an-api-key.mdx b/zh/development/api-development/getting-an-api-key.mdx index 74ed5aa84..fdbb5b88c 100644 --- a/zh/development/api-development/getting-an-api-key.mdx +++ b/zh/development/api-development/getting-an-api-key.mdx @@ -1,6 +1,7 @@ --- title: '获取 API Key' description: '了解如何创建和管理你的 Comfy Platform API Key，用于访问 Cloud API、Partner Nodes 等。' +icon: 'key' --- import GetApiKey from '/snippets/zh/get-api-key.mdx' diff --git a/zh/development/api-development/overview.mdx b/zh/development/api-development/overview.mdx new file mode 100644 index 000000000..f5646c17b --- /dev/null +++ b/zh/development/api-development/overview.mdx @@ -0,0 +1,46 @@ +--- +title: "API 总览" +description: "通过不同方式编程调用 ComfyUI 的接口概览" +icon: "list" +--- + +ComfyUI 提供多种 API 选项，取决于你希望在哪里运行工作流以及你想管理多少基础设施。本页帮助你选择合适的方式。 + +--- + +## 我应该用哪种 API？ + +| | Cloud API | ComfyUI Server API | +|---|---|---| +| **在哪运行** | Comfy Cloud（托管 GPU） | 你自己的机器 | +| **GPU 管理** | 无需操心 | 自己管理硬件 | +| **模型** | 云端预装并由 Comfy 管理 | 自行下载和管理模型 | +| **认证** | `X-API-Key` 请求头 | 无（本地）或 API Key（Partner Nodes）| +| **基础地址** | `https://cloud.comfy.org` | 你自己的服务器地址（例如 `http://localhost:8188`）| +| **协议** | REST + WebSocket | REST + WebSocket | +| **价格** | 订阅制（Creator/Pro 等级） | 免费（用你自己的算力）| +| **适合场景** | 快速集成，无需管理基础设施 | 完全控制、自定义硬件和模型 | + +两种 API 使用相同的 [API 格式](/zh/development/api-development/workflow-api-format) 工作流，你可以在本地开发和测试工作流，然后直接迁移到云端。 + +--- + +## 快速开始 + + + + 在 Comfy 托管的基础设施上运行工作流。无需 GPU 设置。 + + + 将 ComfyUI 作为服务器在本地运行，通过 API 调用。 + + + 在无界面或 API 驱动的工作流中使用付费 Partner Nodes。 + + + +--- + +## 前提条件 + +- 一个 API Key（参见[获取 API Key](/zh/development/api-development/getting-an-api-key)） diff --git a/zh/development/api-development/workflow-api-format.mdx b/zh/development/api-development/workflow-api-format.mdx new file mode 100644 index 000000000..d55e1f2c2 --- /dev/null +++ b/zh/development/api-development/workflow-api-format.mdx @@ -0,0 +1,170 @@ +--- +title: "工作流 API 格式" +description: "理解 ComfyUI 工作流的 API 格式以及如何导出" +icon: "file-code" +--- + +ComfyUI 工作流是描述节点图的 JSON 对象。当你通过 Cloud API 或自建服务器以编程方式调用 ComfyUI 时，工作流必须以 **API 格式**提交——这是一种与浏览器中使用的常规保存格式不同的专用 JSON 结构。 + +本页解释两者的区别以及如何正确导出你的工作流。 + +--- + +## 保存格式 vs API 格式 + +ComfyUI 前端可以以两种格式保存工作流： + +| | 保存格式 | API 格式 | +|---|---|---| +| **菜单路径** | `文件 → 保存` 或 `Ctrl+S` | `文件 → 导出工作流 (API)` | +| **文件后缀** | `.json` | `.json` | +| **节点键** | 节点标题或标签 | 数字节点 ID | +| **组件值** | 包含 | 包含 | +| **位置/布局数据** | 包含 (x, y, width) | **不包含** | +| **颜色/分组** | 包含 | **不包含** | +| **用途** | 在前端重新打开 | API 提交 | +| **可否加载到 UI** | 可以 | 可以，但没有布局 | + +关键区别：**API 格式省略了 UI 元数据**（位置、颜色、分组、节点尺寸），这些仅在前端可视化编辑时需要。这使 JSON 更小、更简洁，适合程序化使用。 + +--- + +## 如何导出 + +在 ComfyUI 前端打开工作流，然后导航到 `文件 → 导出工作流 (API)`： + + + 以 API 格式保存工作流 + + +这将下载一个只包含 API 相关数据的 `.json` 文件： + +```json +{ + "3": { + "inputs": { + "seed": 156680208700286, + "steps": 20, + "cfg": 8, + "sampler_name": "euler", + "scheduler": "normal", + "denoise": 1, + "model": [ + "4", + 0 + ], + "positive": [ + "6", + 0 + ], + "negative": [ + "7", + 0 + ], + "latent_image": [ + "5", + 0 + ] + }, + "class_type": "KSampler", + "_meta": { + "title": "KSampler" + } + }, + "4": { + "inputs": { + "ckpt_name": "v1-5-pruned-emaonly-fp16.safetensors" + }, + "class_type": "CheckpointLoaderSimple", + "_meta": { + "title": "Load Checkpoint" + } + }, + "5": { + "inputs": { + "width": 512, + "height": 512, + "batch_size": 1 + }, + "class_type": "EmptyLatentImage", + "_meta": { + "title": "Empty Latent Image" + } + }, + "6": { + "inputs": { + "text": "beautiful scenery nature glass bottle landscape, , purple galaxy bottle,", + "clip": [ + "4", + 1 + ] + }, + "class_type": "CLIPTextEncode", + "_meta": { + "title": "CLIP Text Encode (Prompt)" + } + }, + "7": { + "inputs": { + "text": "text, watermark", + "clip": [ + "4", + 1 + ] + }, + "class_type": "CLIPTextEncode", + "_meta": { + "title": "CLIP Text Encode (Prompt)" + } + }, + "8": { + "inputs": { + "samples": [ + "3", + 0 + ], + "vae": [ + "4", + 2 + ] + }, + "class_type": "VAEDecode", + "_meta": { + "title": "VAE Decode" + } + }, + "9": { + "inputs": { + "filename_prefix": "ComfyUI", + "images": [ + "8", + 0 + ] + }, + "class_type": "SaveImage", + "_meta": { + "title": "Save Image" + } + } +} +``` + +--- + +## 格式转换 + +如果你有一个保存格式的工作流需要转为 API 格式，最简单的方法是： + +1. 在前端通过 `文件 → 加载` 打开 `.json` 文件 +2. 通过 `文件 → 导出工作流 (API)` 重新导出 + +如果需要自动化转换，可以编写脚本去除每个节点的 `x`、`y`、`width` 字段，并移除根 JSON 中的 `groups` 和 `extra` 部分。 + +--- + +## 相关页面 + +- [API 总览](/zh/development/api-development/overview) — 比较 Cloud 和 Server API 选项 +- [Cloud API 概述](/zh/development/cloud/overview) — 向 Comfy Cloud 提交 API 格式的工作流 +- [API 示例](/zh/development/comfyui-server/api-examples) — 查看 API 格式工作流的使用示例 +- [获取 API Key](/zh/development/api-development/getting-an-api-key) — Cloud API 和 Partner Nodes 所需 diff --git a/zh/development/cloud/api-reference.mdx b/zh/development/cloud/api-reference.mdx index ad70a33e1..0dc2bcd9d 100644 --- a/zh/development/cloud/api-reference.mdx +++ b/zh/development/cloud/api-reference.mdx @@ -1,6 +1,7 @@ --- title: "Cloud API 参考" description: "Comfy Cloud 的完整 API 参考及代码示例" +icon: "book-open" --- import PollJobCompletion from '/snippets/zh/cloud/poll-job-completion.mdx' diff --git a/zh/development/cloud/openapi.mdx b/zh/development/cloud/openapi.mdx index 2241a3029..3ad83c542 100644 --- a/zh/development/cloud/openapi.mdx +++ b/zh/development/cloud/openapi.mdx @@ -1,6 +1,7 @@ --- title: "OpenAPI 规范" description: "Comfy Cloud API 的机器可读的 OpenAPI 规范" +icon: "file-lines" openapi: "/openapi-cloud.yaml" --- diff --git a/zh/development/cloud/overview.mdx b/zh/development/cloud/overview.mdx index cd8a6db8e..02825b558 100644 --- a/zh/development/cloud/overview.mdx +++ b/zh/development/cloud/overview.mdx @@ -37,11 +37,7 @@ https://cloud.comfy.org ### 获取 API 密钥 - - - - 请妥善保管您的 API 密钥。切勿将其提交到版本控制系统或公开分享。 - +请参阅[获取 API 密钥](/zh/development/api-development/getting-an-api-key)了解如何创建和管理 Cloud API 密钥。 ### 使用 API 密钥 @@ -80,7 +76,7 @@ response = requests.get( ### 工作流 -ComfyUI 工作流是描述节点图的 JSON 对象。API 接受"API 格式"的工作流（以节点 ID 为键，包含 class_type、inputs 等），该格式由 ComfyUI 前端的"Save (API Format)"选项导出。 +ComfyUI 工作流是描述节点图的 JSON 对象。API 接受 [API 格式](/zh/development/api-development/workflow-api-format) 的工作流（以节点 ID 为键，包含 class_type、inputs 等），该格式由 ComfyUI 前端的"导出工作流 (API)"选项导出。 ### 任务 diff --git a/zh/development/comfyui-server/api-examples.mdx b/zh/development/comfyui-server/api-examples.mdx new file mode 100644 index 000000000..e5d1d896b --- /dev/null +++ b/zh/development/comfyui-server/api-examples.mdx @@ -0,0 +1,278 @@ +--- +title: "API 示例" +description: "调用 ComfyUI Server API 的三种常见方式" +--- + +本页演示了与 ComfyUI Server API 交互的三种方式，从简单的 HTTP 提交到完整的 WebSocket 集成实时图像输出。 + +所有示例均使用[默认的 SD1.5 工作流](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples)进行演示。使用 API 之前，你需要先导出工作流的 [API 格式](/zh/development/api-development/workflow-api-format)。 + + + 这些示例使用 Python 标准库和 `websocket-client` 包（`pip install websocket-client`）。底层 API 协议与语言无关 — 请参阅 [Cloud API 参考](/zh/development/cloud/api-reference) 了解 TypeScript 和 curl 版本。 + + +--- + +## 方法一：提交即忘（仅 HTTP） + +源码：[`basic_api_example.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/basic_api_example.py) + +最简单的方式：提交工作流，不等待结果。适用于不需要即时输出的场景。 + +```python +"""basic_api_example.py — 仅通过 HTTP 提交工作流。""" + +import json +from urllib import request + +SERVER_ADDRESS = "127.0.0.1:8188" + + +def queue_prompt(prompt): + p = {"prompt": prompt} + data = json.dumps(p).encode("utf-8") + req = request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + request.urlopen(req) + + +if __name__ == "__main__": + # 加载 API 格式导出的工作流 + prompt_text = """{ + "3": { + "class_type": "KSampler", + "inputs": { + "cfg": 8, "denoise": 1, + "latent_image": ["5", 0], + "model": ["4", 0], + "negative": ["7", 0], + "positive": ["6", 0], + "sampler_name": "euler", + "scheduler": "normal", + "seed": 8566257, "steps": 20 + } + }, + "4": { + "class_type": "CheckpointLoaderSimple", + "inputs": {"ckpt_name": "v1-5-pruned-emaonly.safetensors"} + }, + "5": { + "class_type": "EmptyLatentImage", + "inputs": {"batch_size": 1, "height": 512, "width": 512} + }, + "6": { + "class_type": "CLIPTextEncode", + "inputs": {"clip": ["4", 1], "text": "masterpiece best quality man"} + }, + "7": { + "class_type": "CLIPTextEncode", + "inputs": {"clip": ["4", 1], "text": "bad hands"} + }, + "8": { + "class_type": "VAEDecode", + "inputs": {"samples": ["3", 0], "vae": ["4", 2]} + }, + "9": { + "class_type": "SaveImage", + "inputs": {"filename_prefix": "ComfyUI", "images": ["8", 0]} + } + }""" + + prompt = json.loads(prompt_text) + # 提交前修改输入 + prompt["3"]["inputs"]["seed"] = 5 + prompt["6"]["inputs"]["text"] = "masterpiece best quality man" + + queue_prompt(prompt) + print("Prompt submitted successfully.") +``` + + + 此方法使用 `SaveImage` 节点，图片会保存到服务器磁盘。要获取图片，需要调用 `GET /view?filename=...`。 + + +--- + +## 方法二：WebSocket + History（监控执行完成） + +源码：[`websockets_api_example.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/websockets_api_example.py) + +使用 WebSocket 等待执行完成，然后通过 `/history` 端点获取结果。这是大多数场景的推荐方式。 + +```python +"""websockets_api_example.py — 通过 WebSocket 监控执行，通过 /history 下载。""" + +import websocket # pip install websocket-client +import uuid +import json +import urllib.request +import urllib.parse + +SERVER_ADDRESS = "127.0.0.1:8188" +client_id = str(uuid.uuid4()) + + +def queue_prompt(prompt, prompt_id): + p = {"prompt": prompt, "client_id": client_id, "prompt_id": prompt_id} + data = json.dumps(p).encode("utf-8") + req = urllib.request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + urllib.request.urlopen(req) + + +def get_image(filename, subfolder, folder_type): + params = urllib.parse.urlencode({ + "filename": filename, + "subfolder": subfolder, + "type": folder_type, + }) + with urllib.request.urlopen( + f"http://{SERVER_ADDRESS}/view?{params}" + ) as response: + return response.read() + + +def get_history(prompt_id): + with urllib.request.urlopen( + f"http://{SERVER_ADDRESS}/history/{prompt_id}" + ) as response: + return json.loads(response.read()) + + +def get_images(ws, prompt): + prompt_id = str(uuid.uuid4()) + queue_prompt(prompt, prompt_id) + + while True: + out = ws.recv() + if isinstance(out, str): + message = json.loads(out) + if message["type"] == "executing": + data = message["data"] + if data["node"] is None and data["prompt_id"] == prompt_id: + break # 执行完成 + # 二进制帧是预览图片 — 此处跳过 + continue + + history = get_history(prompt_id)[prompt_id] + output_images = {} + for node_id in history["outputs"]: + node_output = history["outputs"][node_id] + images_output = [] + if "images" in node_output: + for image in node_output["images"]: + image_data = get_image( + image["filename"], image["subfolder"], image["type"] + ) + images_output.append(image_data) + output_images[node_id] = images_output + return output_images + + +if __name__ == "__main__": + # 此处省略完整工作流 JSON，请参考方法一的示例 + # prompt = json.loads(prompt_text) + # prompt["3"]["inputs"]["seed"] = 5 + # prompt["6"]["inputs"]["text"] = "masterpiece best quality man" + + # ws = websocket.WebSocket() + # ws.connect(f"ws://{SERVER_ADDRESS}/ws?clientId={client_id}") + # images = get_images(ws, prompt) + # ws.close() + pass +``` + + + WebSocket 二进制帧中的生成过程预览图片可以解码用于实时预览（二进制格式参见[服务器消息](/zh/development/comfyui-server/comms_messages)页面）。 + + +--- + +## 方法三：WebSocket 配合 SaveImageWebsocket（实时获取图片） + +源码：[`websockets_api_example_ws_images.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/websockets_api_example_ws_images.py) + +如果不想将图片保存到磁盘，可以使用 `SaveImageWebsocket` 节点。图片会通过 WebSocket 二进制帧直接传送。 + +```python +"""websockets_api_example_ws_images.py — 通过 WebSocket 直接接收图片。""" + +import websocket # pip install websocket-client +import uuid +import json +import urllib.request +import urllib.parse + +SERVER_ADDRESS = "127.0.0.1:8188" +client_id = str(uuid.uuid4()) + + +def queue_prompt(prompt): + p = {"prompt": prompt, "client_id": client_id} + data = json.dumps(p).encode("utf-8") + req = urllib.request.Request( + f"http://{SERVER_ADDRESS}/prompt", data=data + ) + return json.loads(urllib.request.urlopen(req).read()) + + +def get_images(ws, prompt): + prompt_id = queue_prompt(prompt)["prompt_id"] + output_images = {} + current_node = "" + + while True: + out = ws.recv() + if isinstance(out, str): + message = json.loads(out) + if message["type"] == "executing": + data = message["data"] + if data["prompt_id"] == prompt_id: + if data["node"] is None: + break # 执行完成 + current_node = data["node"] + else: + # 二进制帧 — SaveImageWebsocket 的图片数据 + if current_node == "save_image_websocket_node": + images_output = output_images.get(current_node, []) + # 前 8 字节是类型/元数据，剩余是图片数据 + images_output.append(out[8:]) + output_images[current_node] = images_output + + return output_images + + +if __name__ == "__main__": + # prompt = json.loads(prompt_text) + # prompt["3"]["inputs"]["seed"] = 5 + + # ws = websocket.WebSocket() + # ws.connect(f"ws://{SERVER_ADDRESS}/ws?clientId={client_id}") + # images = get_images(ws, prompt) + # ws.close() + pass +``` + + + 工作流必须使用 `class_type: "SaveImageWebsocket"`（内置节点）代替普通的 `SaveImage` 节点。 + + +--- + +## 应该用哪种方法？ + + + + **发送即忘。** 适用于不需要立即获取输出的场景。 + + + **推荐。** 等待完成，然后下载结果。简单性和可靠性之间最佳平衡。 + + + **实时图片。** 适用于需要图片不写磁盘直接送达的交互式应用。 + + + +完整的 API 参考（端点、负载格式、错误处理）请参阅[服务器路由](/zh/development/comfyui-server/comms_routes)和[服务器消息](/zh/development/comfyui-server/comms_messages)页面。 diff --git a/zh/development/comfyui-server/api-key-integration.mdx b/zh/development/comfyui-server/api-key-integration.mdx index bdae8ad49..b3313ad00 100644 --- a/zh/development/comfyui-server/api-key-integration.mdx +++ b/zh/development/comfyui-server/api-key-integration.mdx @@ -2,6 +2,7 @@ title: '通过 API Key 集成来使用 ComfyUI API 节点' description: '本文介绍了如何通过 API Key 集成来使用 ComfyUI API 节点' sidebarTitle: 'Partner Node API 集成' +icon: 'puzzle-piece' --- 从[PR #8041](https://github.com/Comfy-Org/ComfyUI/pull/8041)开始，ComfyUI 支持通过创建 API Key 来直接使用 ComfyUI 内置的 API 节点，无需特定的前端界面（甚至可以完全不使用前端）。 diff --git a/zh/development/comfyui-server/comms_messages.mdx b/zh/development/comfyui-server/comms_messages.mdx index c92fe5f31..6bcc74fa9 100644 --- a/zh/development/comfyui-server/comms_messages.mdx +++ b/zh/development/comfyui-server/comms_messages.mdx @@ -1,5 +1,6 @@ --- title: "消息传递" +icon: "comment" --- ## 消息传递机制 diff --git a/zh/development/comfyui-server/comms_overview.mdx b/zh/development/comfyui-server/comms_overview.mdx index 8366cb9d8..8c206faff 100644 --- a/zh/development/comfyui-server/comms_overview.mdx +++ b/zh/development/comfyui-server/comms_overview.mdx @@ -1,16 +1,70 @@ --- -title: "服务器概览" +title: "服务器概述" +description: "将 ComfyUI 作为服务器运行，通过 REST 和 WebSocket API 编程交互" --- -## 概览 +ComfyUI 默认作为 HTTP 服务器在本地运行。你可以通过编程方式调用它来提交工作流、上传文件、下载输出和监控进度 — 无需打开浏览器。 + +## 启动服务器 + +启动 ComfyUI 时会自动启动 HTTP 服务器，地址为 `http://127.0.0.1:8188`。 + +以无界面模式运行（不打开浏览器）： + + +```bash +# 不打开浏览器运行 +python main.py --headless +``` + +```bash +# 指定自定义端口 +python main.py --port 8288 +``` + +```bash +# 监听所有网络接口（用于远程访问） +python main.py --listen 0.0.0.0 +``` + + + + 查看完整启动参数请运行 `python main.py --help`，或参阅[安装指南](/zh/installation/manual_install#basic-usage)。 + + +## 本部分的关键页面 + + + + 可用的 HTTP 端点：提交工作流、上传文件、查询状态。 + + + 调用 API 的代码示例：仅 HTTP、WebSocket + History、SaveImageWebsocket。 + + + 执行过程中服务器发送给客户端的 WebSocket 消息类型。 + + + 高级：反转执行以实现自定义控制流。 + + + +## 使用 Partner Nodes + +如果工作流包含付费 Partner Nodes，可在请求体中包含 API Key。详见 [Partner Node API 集成](/zh/development/comfyui-server/api-key-integration) 指南。 + +--- + +## 服务器工作原理 Comfy 服务器构建于 [aiohttp 框架](https://docs.aiohttp.org/) 基础之上，该框架则依赖于 [asyncio](https://pypi.org/project/asyncio/) 库。 -服务器向客户端发送消息时，会通过其 `send_sync` 方法（该服务器是 `server.py` 文件中定义的 `PromptServer` 类的一个实例）以 `socket` 消息的形式进行。这些消息由注册在 `api.js` 文件中的 `socket` 事件监听器负责处理。更多详情请参阅[消息传递](/zh/development/comfyui-server/comms_messages)。 +服务器向客户端发送消息时，会通过 `send_sync` 方法（`server.py` 中定义的 `PromptServer` 类实例）以 socket 消息形式发送。这些消息由 `api.js` 中注册的 socket 事件监听器处理。参见[消息传递](/zh/development/comfyui-server/comms_messages)。 -客户端向服务器发送消息时，则通过 `api.js` 文件中定义的 `api.fetchApi()` 方法进行，这些请求由服务器端设定的 HTTP 路由负责处理。更多详情请参阅[路由机制](/zh/development/comfyui-server/comms_routes)部分。 +客户端向服务器发送消息时，通过 `api.js` 中定义的 `api.fetchApi()` 方法，由服务器端设定的 HTTP 路由处理。参见[路由机制](/zh/development/comfyui-server/comms_routes)。 -当您将一个请求加入处理队列时，客户端会提交完整的工作流信息（包括所有小部件的当前值）。 -一旦请求进入队列，服务器将不会接收您在此之后对工作流所做的任何修改。 -若希望在程序执行过程中动态调整服务器行为，则需要借助路由机制来实现。 -python3 .github/scripts/validate-links.py \ No newline at end of file + + 当请求加入队列时，客户端会提交完整的工作流（包括所有组件的当前值）。 + 一旦请求进入队列，服务器不会接收之后对工作流的任何修改。 + 若需在执行过程中动态调整服务器行为，需要使用路由机制。 + diff --git a/zh/development/comfyui-server/comms_routes.mdx b/zh/development/comfyui-server/comms_routes.mdx index eb84763bd..4db7b8276 100644 --- a/zh/development/comfyui-server/comms_routes.mdx +++ b/zh/development/comfyui-server/comms_routes.mdx @@ -1,5 +1,6 @@ --- title: "路由" +icon: "route" --- ## 路由 diff --git a/zh/development/comfyui-server/execution_model_inversion_guide.mdx b/zh/development/comfyui-server/execution_model_inversion_guide.mdx index f2afe83a9..82db16c02 100644 --- a/zh/development/comfyui-server/execution_model_inversion_guide.mdx +++ b/zh/development/comfyui-server/execution_model_inversion_guide.mdx @@ -1,5 +1,6 @@ --- title: "执行模型反转指南" +icon: "code-branch" --- [PR #2666](https://github.com/Comfy-Org/ComfyUI/pull/2666) 将执行模型从原先的“后端到前端”递归方式，转变为“前端到后端”的拓扑排序方式。尽管多数自定义节点预计仍能照常工作，本指南旨在帮助自定义节点开发者识别那些*可能*因此变更而出现问题的情况。