Skip to content

Commit

Permalink
docs: improved docs around "input.images", fixed some typos, added mo…
Browse files Browse the repository at this point in the history 
…re links to the runpod docs
  • Loading branch information
@TimPietrusky
TimPietrusky committed Dec 3, 2023
1 parent 5f5e390 commit 2531eb1
Showing 1 changed file with 28 additions and 33 deletions.
61 changes: 28 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@
* [Upload image to AWS S3](#upload-image-to-aws-s3)
- [Use the Docker image on RunPod](#use-the-docker-image-on-runpod)
- [API specification](#api-specification)
* [JSON Payload Structure](#json-payload-structure)
* [JSON Request Body](#json-request-body)
* [Fields](#fields)
+ ["input.images" details](#inputimages-details)
+ ["input.images"](#inputimages)
- [Interact with your RunPod API](#interact-with-your-runpod-api)
* [Health status](#health-status)
* [Generate an image](#generate-an-image)
Expand All @@ -31,7 +31,7 @@
* [Test: handler](#test-handler)
* [Test: docker image](#test-docker-image)
- [Automatically deploy to Docker hub with Github Actions](#automatically-deploy-to-docker-hub-with-github-actions)
- [Acknowledgements](#acknowledgements)
- [Acknowledgments](#acknowledgments)

<!-- tocstop -->

Expand All @@ -47,7 +47,7 @@

- Run any [ComfyUI](https://github.com/comfyanonymous/ComfyUI) workflow to generate an image
- Provide input images as base64-encoded string
- Generated image is either:
- The generated image is either:
- Returned as base64-encoded string (default)
- Uploaded to AWS S3 ([if AWS S3 is configured](#upload-image-to-aws-s3))
- Build-in checkpoint:
Expand Down Expand Up @@ -94,9 +94,9 @@ This is only needed if you want to upload the generated picture to AWS S3. If yo
- Navigate to [`Serverless > Endpoints`](https://www.runpod.io/console/serverless/user/endpoints) and click on `New Endpoint`
- In the dialog, configure:
- Endpoint Name: `comfy`
- Select Template: `runpow-worker-comfy` (or what ever name you gave your template)
- Active Workers: `0` (what ever makes sense for you)
- Max Workers: `3` (what ever makes sense for you)
- Select Template: `runpow-worker-comfy` (or whatever name you gave your template)
- Active Workers: `0` (whatever makes sense for you)
- Max Workers: `3` (whatever makes sense for you)
- Idle Timeout: `5` (you can leave the default)
- Flash Boot: `enabled` (doesn't cost more, but provides faster boot of our worker, which is good)
- Advanced: Leave the defaults
Expand All @@ -107,9 +107,9 @@ This is only needed if you want to upload the generated picture to AWS S3. If yo

## API specification

The following is the required structure and format for requests made to the API.
The following describes which fields exist when doing requests to the API. We only describe the fields that are sent via `input` as those are needed by the worker itself. For a full list of fields, please take a look at the [official documentation](https://docs.runpod.io/docs/serverless-usage).

### JSON Payload Structure
### JSON Request Body

```json
{
Expand All @@ -127,19 +127,23 @@ The following is the required structure and format for requests made to the API.

### Fields

| Field Path | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------------- |
| `input` | Object | Yes | The top-level object containing the request data. |
| `input.workflow` | Object | Yes | Contains the ComfyUI workflow configuration. |
| `input.images` | Array | No | An array of images. |
| Field Path | Type | Required | Description |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `input` | Object | Yes | The top-level object containing the request data. |
| `input.workflow` | Object | Yes | Contains the ComfyUI workflow configuration. |
| `input.images` | Array | No | An array of images. Each image will be added into the "input"-folder of ComfyUI and can then be used in the workflow by using it's `name` |


#### "input.images" details
#### "input.images"

An array of images, where each image should have a different name.

🚨 The request body for a RunPod endpoint is 10 MB for `/run` and 20 MB for `/runsync`, so make sure that your input images are not super huge as this will be blocked by RunPod otherwise, see the [official documentation](https://docs.runpod.io/docs/serverless-endpoint-urls)

| Field Name | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `name` | String | No | The name of the image. Please use the same name in your workflow to reference the image. |
| `image` | String | No | A base64 encoded string of the image. |
| `name` | String | Yes | The name of the image. Please use the same name in your workflow to reference the image. |
| `image` | String | Yes | A base64 encoded string of the image. |



Expand All @@ -163,30 +167,20 @@ curl -H "Authorization: Bearer <api_key>" https://api.runpod.ai/v2/<endpoint_id>

You can either create a new job async by using `/run` or a sync by using runsync. The example here is using a sync job and waits until the response is delivered.

The API expects a JSON in this form, where `workflow` is the [workflow from ComfyUI, exported as JSON](#how-to-get-the-workflow-from-comfyui):

```json
{
"input": {
"workflow": {
// ComfyUI workflow
},
}
}
```
The API expects a [JSON in this form](#json-request-body), where `workflow` is the [workflow from ComfyUI, exported as JSON](#how-to-get-the-workflow-from-comfyui) and `images` is optional.

Please also take a look at the [test_input.json](./test_input.json) to see how the API input should look like.

#### Example request with cURL

```bash
curl -X POST -H "Authorization: Bearer <api_key>" -H "Content-Type: application/json" -d '{"input":{"workflow":{"3":{"inputs":{"seed":1337,"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"},"4":{"inputs":{"ckpt_name":"sd_xl_base_1.0.safetensors"},"class_type":"CheckpointLoaderSimple"},"5":{"inputs":{"width":512,"height":512,"batch_size":1},"class_type":"EmptyLatentImage"},"6":{"inputs":{"text":"beautiful scenery nature glass bottle landscape, , purple galaxy bottle,","clip":["4",1]},"class_type":"CLIPTextEncode"},"7":{"inputs":{"text":"text, watermark","clip":["4",1]},"class_type":"CLIPTextEncode"},"8":{"inputs":{"samples":["3",0],"vae":["4",2]},"class_type":"VAEDecode"},"9":{"inputs":{"filename_prefix":"ComfyUI","images":["8",0]},"class_type":"SaveImage"}}}}' https://api.runpod.ai/v2/<endpoint_id>/runsync
curl -X POST -H "Authorization: Bearer <api_key>" -H "Content-Type: application/json" -d '{"input":{"workflow":{"3":{"inputs":{"seed":1337,"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"},"4":{"inputs":{"ckpt_name":"sd_xl_base_1.0.safetensors"},"class_type":"CheckpointLoaderSimple"},"5":{"inputs":{"width":512,"height":512,"batch_size":1},"class_type":"EmptyLatentImage"},"6":{"inputs":{"text":"beautiful scenery nature glass bottle landscape, purple galaxy bottle,","clip":["4",1]},"class_type":"CLIPTextEncode"},"7":{"inputs":{"text":"text, watermark","clip":["4",1]},"class_type":"CLIPTextEncode"},"8":{"inputs":{"samples":["3",0],"vae":["4",2]},"class_type":"VAEDecode"},"9":{"inputs":{"filename_prefix":"ComfyUI","images":["8",0]},"class_type":"SaveImage"}}}}' https://api.runpod.ai/v2/<endpoint_id>/runsync

# Response with AWS S3 bucket configuration
# {"delayTime":2188,"executionTime":2297,"id":"sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1","output":{"message":"https://bucket.s3.region.amazonaws.com/10-23/sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1/c67ad621.png","status":"success"},"status":"COMPLETED"}

# Response as base64-encoded image
#
# {"delayTime":2188,"executionTime":2297,"id":"sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1","output":{"message":"base64encodedimage","status":"success"},"status":"COMPLETED"}
```

## How to get the workflow from ComfyUI?
Expand Down Expand Up @@ -243,15 +237,15 @@ To run the Docker image on Windows, we need to have WSL2 and a Linux distro (lik
- If you want to run a specific test: `python -m unittest tests.test_rp_handler.TestRunpodWorkerComfy.test_bucket_endpoint_not_configured`

You can also start the handler itself to have the local server running: `python src/rp_handler.py`
In order to get this to work you will also need to start "ComfyUI", otherwise the handler will not work.
To get this to work you will also need to start "ComfyUI", otherwise the handler will not work.

### Test: docker image

- If you want to run the Docker container, you can use: `docker-compose up`

## Automatically deploy to Docker hub with Github Actions

The repo contains two workflows that publishes the image to Docker hub using Github Actions:
The repo contains two workflows that publish the image to Docker hub using Github Actions:

- [docker-dev.yml](.github/workflows/docker-dev.yml): Creates the image and pushes it to Docker hub with the `dev` tag on every push to the `main` branch
- [docker-release.yml](.github/workflows/docker-release.yml): Creates the image and pushes it to Docker hub with the `latest` and the release tag. It will only be triggered when you create a release on GitHub
Expand All @@ -265,7 +259,8 @@ If you want to use this, you should add these secrets to your repository:
| `DOCKERHUB_REPO` | The repository on Docker Hub where the image will be pushed. | `timpietruskyblibla` |
| `DOCKERHUB_IMG` | The name of the image to be pushed to Docker Hub. | `runpod-worker-comfy` |

## Acknowledgements

## Acknowledgments

- Thanks to [all contributors](https://github.com/blib-la/runpod-worker-comfy/graphs/contributors) for your awesome work
- Thanks to [Justin Merrell](https://github.com/justinmerrell) from RunPod for [worker-1111](https://github.com/runpod-workers/worker-a1111), which was used to get inspired on how to create this worker
Expand Down

0 comments on commit 2531eb1

Please sign in to comment.