Skip to main content
These endpoints let you run models listed in the Playground in the background. Submit a job, check progress, fetch the result, or cancel while it’s still queued.

​
Endpoints

Base URL: https://model-api.runcomfy.net
EndpointMethodPurpose
/v1/models/{model_id}POSTSubmit an asynchronous request
/v1/requests/{request_id}/statusGETCheck request status
/v1/requests/{request_id}/resultGETRetrieve request result
/v1/requests/{request_id}/cancelPOSTCancel a queued request

​
Common Path Parameters

model_id string (required). The identifier of the model you want to run (e.g., blackforestlabs/flux-1-kontext/pro/edit). Alt RunComfy model id request_id string (required for non‑submit endpoints). Returned by POST /v1/models/{model_id}; use it to check status, fetch result, or cancel.

​
Submit a Request

Submit an asynchronous request to a Playground model. Returns a request_id and convenience URLs to poll and fetch results. 
POST /v1/models/{model_id}

​
Request Example

Example using the blackforestlabs/flux-1-kontext/pro/edit model: 
curl --request POST \
  --url https://model-api.runcomfy.net/v1/models/blackforestlabs/flux-1-kontext/pro/edit \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "prompt": "She is now holding an orange umbrella and smiling",
    "image_url": "https://playgrounds-storage-public.runcomfy.net/tools/7063/media-files/usecase1-1-input.webp",
    "seed": 81030369,
    "aspect_ratio": "16:9"
  }'
Request body keys (e.g., prompt, image_url, seed, aspect_ratio) map 1:1 to this model’s Input schema. See the model’s API page in the Playground for required fields, types, enums, and defaults. For reference, see the Input schema on the blackforestlabs/flux-1-kontext/pro/edit API page. Alt RunComfy playground model input schema

​
Response Example

{
  "request_id": "{request_id}",
  "status_url": "https://model-api.runcomfy.net/v1/requests/{request_id}/status",
  "result_url": "https://model-api.runcomfy.net/v1/requests/{request_id}/result",
  "cancel_url": "https://model-api.runcomfy.net/v1/requests/{request_id}/cancel"
}
Successful requests return 200 OK with a JSON object providing request tracking details.
  • request_id (string): Unique identifier for the request.
  • status_url (string): URL to poll for request progress.
  • result_url (string): URL to fetch outputs once the request completes.
  • cancel_url (string): URL to cancel the request if still queued.

​
Monitor Request Status

Poll the current state for a request_id. Typical states are: in_queue → in_progress → completed (or cancelled). 
GET /v1/requests/{request_id}/status

​
Request Example

curl --request GET \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/status \
  --header "Authorization: Bearer <token>"

​
Response Example

{
  "request_id": "{request_id}",
  "status": "in_queue",
  "queue_position": 3,
  "status_url": "https://model-api.runcomfy.net/v1/requests/{request_id}/status",
  "result_url": "https://model-api.runcomfy.net/v1/requests/{request_id}/result"
}
Successful requests return a 200 OK status with a JSON object describing the request’s state.
  • status (string): States while polling: in_queue, in_progress, completed, cancelled.
  • status_url (string): URL to poll for request progress.
  • result_url (string): URL to fetch outputs once the request completes.
  • For in_queue, queue_position (integer): Your position in the queue.

​
Retrieve Request Results

When status is completed, fetch the final outputs. The shape of result (single URI vs. object/array) is defined by the model’s Output schema on its API page in the Playground. 
GET /v1/requests/{request_id}/result

​
Request Example

curl --request GET \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/result \
  --header "Authorization: Bearer <token>"

​
Response Example

{
  "request_id": "{request_id}",
  "status": "succeeded",
  "output": {
    "image": "https://playgrounds-storage-public.runcomfy.net/a.png",
    "videos": [
      "https://playgrounds-storage-public.runcomfy.net/a.mp4",
      "https://playgrounds-storage-public.runcomfy.net/b.mp4",
      "https://playgrounds-storage-public.runcomfy.net/c.mp4"
    ]
  }
}
Successful requests return 200 OK with a JSON object containing the request’s final details.
  • status (string): One of succeeded, failed, in_queue, in_progress, or cancelled.
  • output (object, present only when status is succeeded): a single URL string (one file) or an array of URL strings (multiple files).
  • created_at (string): When the request was created.
  • finished_at (string): When the request completed.

​
Cancel a Request

Cancel a request that is still queued. Already completed or terminated requests will be no‑ops. 
POST /v1/requests/{request_id}/cancel

​
Request Example

curl --request POST \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/cancel \
  --header "Authorization: Bearer <token>"

​
Response Example

{
  "request_id": "{request_id}",
  "status": "completed"
  "outcome": "cancelled"
}
Successful requests return a 202 Accepted status with a JSON object containing the cancellation outcome.
  • outcome (string): cancelled if the cancellation is accepted; not_cancellable if the request is already in progress or completed.

​
Image/Video/Audio Inputs

Use a publicly accessible HTTPS URL that returns the file with an unauthenticated GET request (no cookies or auth headers). Prefer stable or pre‑signed URLs for private assets. 
{
  "image_url": "https://playgrounds-storage-public.runcomfy.net/tools/7063/media-files/usecase1-1-input.webp"
}