Introduction

The reference is your key to a comprehensive understanding of the RunComfy API.

<aside> ❗ You need an API key to interact with the RunComfy API. You can find your API key after you signed in to RunComfy.

</aside>

Conventions

The base URL to send all API requests is https://api.runcomfy.net. Please pay special attention that it is .net instead of .com. HTTPS is required for all API requests.

The RunComfy API follows RESTful conventions when possible, with most operations performed via GET, POST, PATCH, and DELETE requests on resources. Request and response bodies are encoded as JSON.

SUPPORTED ENDPOINTS

Authorization

RunComfy uses Bearer Token authorization, once you get the token from your user profile, please add the following to your request Headers, such as the curl below,

curl --location '<https://beta-api.runcomfy.net/prod/api/users/xxxxx/workflows>' \\
--header 'Authorization: Bearer api_token_string'

Integration Process

1. Preparation

   1. UserID

      1. Grab your userId from the dashboard url once you signed in.

      

   2. Token

      1. There are two tokens, Token1 and Token2, in the user profile and you can use either one to call RunComfy API. Token2 is for token rotation when you need to refresh Token1.

      

2. (Https request) Send a request to get all workflows in your account and grab the version_id (attn! version_id) of the workflow you want to launch the machine with.

3. (Https request) Issue a POST request to launch a machine, please note this request will return right away with a server_id.

   1. server_type options:
      1. medium
      2. large
      3. extra-large
      4. 2x-large
      5. 2xl-turbo
   2. estimated_durationis a time span in seconds, for instance, you can set 86400 for one day. You can issue another POST request to change this value after the machine is Ready.

4. (Https request) Poll the current machine launching status using the server_id until the status is Ready. You are NOT charged until the machine status is Ready.

   1. Once the status is Ready, the main_service_url will show up in the response and that url is the ComfyUI url to call queue prompt at.
   2. You can also connect with websocket(wss) to the main_service_url to get the ComfyUI queue status.
   3. See a simple guide here for how to work with ComfyUI backend API.

5. (Https request) Modify the machine running duration to adjust to your specific running scenario. For instance, if you have two running machines and the request queue to your service is dropping, you might consider shortening the running duration of one of your machines or just stop it right away using the request below.

6. (Https request) Stop the machine by calling the DELETE machine API. Once the DELETE request is returned with 200, the machine charge is stopped right away.

Request Limits

To ensure a consistent developer experience for all API users, the RunComfy API is rate limited and size limits apply to request parameters.

Rate Limits

Rate-limited requests will return a "rate_limited" error code (HTTP response status 429). The rate limit for incoming requests per account is one request per second. Some bursts beyond the average rate are allowed.

<aside> ❗ Rate limits may change

In the future, we plan to adjust rate limits to balance for demand and reliability.

</aside>