zlei6/ComfyUI
1
0
Fork 0
mirror of https://github.com/Comfy-Org/ComfyUI.git synced 2026-08-16 22:46:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(openapi): sync shared API contract from cloud@94d0f1b

Browse Source
This commit is contained in:
mattmillerai
2026-08-13 18:25:14 +00:00
committed by github-actions[bot]
parent 2f35f4a081
commit 3211be495a
1 changed files with 305 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

321
openapi.yaml
View File

@@ -35,6 +35,10 @@ components:
description: Timestamp when the asset was last accessed
format: date-time
type: string
loader_path:
description: The bare value a loader widget consumes for this asset. For models it is the path inside the category folder (e.g. "flux.safetensors" for "models/checkpoints/flux.safetensors"), which is what the model resolver matches. For input/output/temp it is the content hash, because those assets are fetched by hash rather than staged by name — that is the value LoadImage-style widgets must carry. Clients add the "[output]"/"[temp]" annotation from the asset's own type, so it is never included here. Null when no such value can be derived.
nullable: true
type: string
metadata:
additionalProperties: true
description: System-managed metadata from download sources (HuggingFace, CivitAI, etc.) - read-only, not user-modifiable
@@ -165,6 +169,10 @@ components:
format: uuid
nullable: true
type: string
loader_path:
description: The bare value a loader widget consumes for this asset. For models it is the path inside the category folder (e.g. "flux.safetensors" for "models/checkpoints/flux.safetensors"), which is what the model resolver matches. For input/output/temp it is the content hash, because those assets are fetched by hash rather than staged by name — that is the value LoadImage-style widgets must carry. Clients add the "[output]"/"[temp]" annotation from the asset's own type, so it is never included here. Null when no such value can be derived.
nullable: true
type: string
mime_type:
description: Updated MIME type of the asset
type: string
@@ -188,6 +196,31 @@ components:
- id
- updated_at
type: object
ChurnkeyAuthResponse:
description: |
Credentials the Churnkey embed requires to launch the cancel flow.
`auth_hash` is hex-encoded HMAC-SHA256 of `customer_id` signed with the
server's CHURNKEY_HMAC_SECRET; it is bound to that single customer ID
and must not be reused for other customers.
properties:
auth_hash:
description: Hex-encoded HMAC-SHA256(customer_id, CHURNKEY_HMAC_SECRET)
type: string
customer_id:
description: Stripe customer ID for the workspace
type: string
mode:
description: Churnkey environment matching the configured app
enum:
- live
- test
- sandbox
type: string
required:
- customer_id
- auth_hash
- mode
type: object
CreateWorkflowRequest:
description: Request body for creating a new saved workflow.
properties:
@@ -511,6 +544,25 @@ components:
required:
- history
type: object
JobAssetsResponse:
description: Paginated list of the assets produced by a single job.
properties:
assets:
description: The job's output assets for the requested page (empty when the job produced none)
items:
$ref: '#/components/schemas/JobOutputAsset'
type: array
job_id:
description: ID of the job these assets belong to
format: uuid
type: string
pagination:
$ref: '#/components/schemas/PaginationInfo'
required:
- job_id
- assets
- pagination
type: object
JobCancelResponse:
description: Response for POST /api/jobs/{job_id}/cancel. Returned on both fresh cancels and idempotent no-ops.
properties:
@@ -565,6 +617,9 @@ components:
additionalProperties: true
description: Primary preview output (only for terminal states)
type: object
previewable_outputs_count:
description: Count of outputs classified as previewable media types (images, video, audio, 3D, text) — a subset of outputs_count (omitted for non-terminal states)
type: integer
status:
description: User-friendly job status
enum:
@@ -597,6 +652,13 @@ components:
workflow_id:
description: UUID identifying the workflow graph definition
type: string
workflow_version_id:
description: |
UUID of the cloud workflow version this job is pinned to, if the
submission carried one (see PromptRequest's workflow_version_id).
Absent for jobs submitted without that association, including
every job submitted through the public API v2 today.
type: string
workspace_id:
description: |
ID of the workspace that owns this job. A successful (200)
@@ -645,6 +707,9 @@ components:
additionalProperties: true
description: Primary preview output (only present for terminal states)
type: object
previewable_outputs_count:
description: Count of outputs classified as previewable media types (images, video, audio, 3D, text) — a subset of outputs_count (omitted for non-terminal states)
type: integer
status:
description: User-friendly job status
enum:
@@ -662,6 +727,56 @@ components:
- status
- create_time
type: object
JobOutputAsset:
description: |
An asset produced by a job, enriched with the per-output node context
(`node_id`, `output_key`, `output_index`) correlated from the job's
execution outputs by content hash. The node-context fields are null
when the asset cannot be matched to an output entry.
properties:
created_at:
description: Timestamp when the asset was created
format: date-time
type: string
hash:
description: Blake3 hash of the asset content.
pattern: ^blake3:[a-f0-9]{64}$
type: string
id:
description: Unique identifier for the asset
format: uuid
type: string
mime_type:
description: MIME type of the asset
type: string
name:
description: Name of the asset file
type: string
node_id:
description: ID of the workflow node that produced this asset, if known
nullable: true
type: string
output_index:
description: Zero-based index of this asset within the node's output slot, if known
nullable: true
type: integer
output_key:
description: Output slot key under the producing node (e.g. "images"), if known
nullable: true
type: string
preview_url:
description: Relative URL for asset preview/thumbnail
format: uri-reference
type: string
size:
description: Size of the asset in bytes
format: int64
type: integer
required:
- id
- name
- created_at
type: object
JobStatusResponse:
description: Job status information
properties:
@@ -1522,7 +1637,11 @@ paths:
operationId: listAssets
parameters:
- deprecated: true
description: 'Deprecated alias of tags_all: filter assets that have ALL of these tags'
description: |
Deprecated alias for `tags_all`, kept permanently for existing
callers. Filter assets that have ALL of these tags. Combining it
with `tags_all`, or exceeding 100 tags (counted after removing
empty values and duplicates), returns 400 `INVALID_TAG_FILTER`.
explode: false
in: query
name: include_tags
@@ -1532,7 +1651,11 @@ paths:
type: array
style: form
- deprecated: true
description: 'Deprecated alias of tags_none: exclude assets that have ANY of these tags'
description: |
Deprecated alias for `tags_none`, kept permanently for existing
callers. Exclude assets that have ANY of these tags. Combining it
with `tags_none`, or exceeding 100 tags (counted after removing
empty values and duplicates), returns 400 `INVALID_TAG_FILTER`.
explode: false
in: query
name: exclude_tags
@@ -1541,7 +1664,14 @@ paths:
type: string
type: array
style: form
- description: Filter assets that have ALL of these tags
- description: |
Filter assets that have ALL of these tags. Tag values are opaque
byte-strings compared exactly and case-sensitively; unknown tags
are not an error — they simply match nothing. Replaces the
deprecated `include_tags`. Sending both spellings, listing the
same tag here and in `tags_none`, or exceeding 100 tags per list
(counted after removing empty values and duplicates) returns 400
`INVALID_TAG_FILTER`.
explode: false
in: query
name: tags_all
@@ -1550,7 +1680,14 @@ paths:
type: string
type: array
style: form
- description: Filter assets that have AT LEAST ONE of these tags
- description: |
Filter assets that have AT LEAST ONE of these tags. Combines with
`tags_all`/`tags_none` by intersection (`tags_none` always wins;
overlap with `tags_none` is allowed and leaves a dead term).
Supplying a positive tag filter (`tags_any`, `tags_all`, or
`include_tags`) replaces the default category filter that is
otherwise applied. Lists over 100 tags (counted after removing
empty values and duplicates) return 400 `INVALID_TAG_FILTER`.
explode: false
in: query
name: tags_any
@@ -1559,7 +1696,11 @@ paths:
type: string
type: array
style: form
- description: Exclude assets that have ANY of these tags
- description: |
Exclude assets that have ANY of these tags. Replaces the
deprecated `exclude_tags`. Sending both spellings, or exceeding
100 tags per list (counted after removing empty values and
duplicates), returns 400 `INVALID_TAG_FILTER`.
explode: false
in: query
name: tags_none
@@ -2342,7 +2483,11 @@ paths:
operationId: getAssetTagHistogram
parameters:
- deprecated: true
description: 'Deprecated alias of tags_all: filter assets that have ALL of these tags'
description: |
Deprecated alias for `tags_all`, kept permanently for existing
callers. Filter assets that have ALL of these tags. The same
combination and list-size rules as on `/api/assets` apply
(400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: include_tags
@@ -2352,7 +2497,11 @@ paths:
type: array
style: form
- deprecated: true
description: 'Deprecated alias of tags_none: exclude assets that have ANY of these tags'
description: |
Deprecated alias for `tags_none`, kept permanently for existing
callers. Exclude assets that have ANY of these tags. The same
combination and list-size rules as on `/api/assets` apply
(400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: exclude_tags
@@ -2361,7 +2510,10 @@ paths:
type: string
type: array
style: form
- description: Filter assets that have ALL of these tags
- description: |
Filter assets that have ALL of these tags. Replaces the deprecated
`include_tags`. The same combination and list-size rules as on
`/api/assets` apply (400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: tags_all
@@ -2370,7 +2522,11 @@ paths:
type: string
type: array
style: form
- description: Filter assets that have AT LEAST ONE of these tags
- description: |
Filter assets that have AT LEAST ONE of these tags. Combines with
`tags_all`/`tags_none` by intersection (`tags_none` always wins).
The same combination and list-size rules as on `/api/assets` apply
(400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: tags_any
@@ -2379,7 +2535,10 @@ paths:
type: string
type: array
style: form
- description: Exclude assets that have ANY of these tags
- description: |
Exclude assets that have ANY of these tags. Replaces the deprecated
`exclude_tags`. The same combination and list-size rules as on
`/api/assets` apply (400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: tags_none
@@ -2440,6 +2599,49 @@ paths:
summary: Get tag histogram for filtered assets
tags:
- file
/api/billing/churnkey/auth:
get:
description: |
Returns the Stripe customer identifier and a server-signed
HMAC-SHA256 of the customer ID, used to launch the Churnkey-hosted
cancellation flow embed.
operationId: getChurnkeyAuth
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ChurnkeyAuthResponse'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workspace has no Stripe customer (never subscribed)
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
"503":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Churnkey is not configured on the server
security:
- BearerAuth: []
summary: Get Churnkey HMAC auth credentials
tags:
- billing
/api/embeddings:
get:
description: Returns the list of text-encoder embeddings available on disk.
@@ -2460,9 +2662,10 @@ paths:
Returns a list of model folders available in the system.
This is an experimental endpoint that replaces the legacy /models endpoint.
Each folder's name is the identifier to pass to /api/experiment/models/{folder}.
Once the model_type migration is active the names are model_type folder_names
(e.g. `ultralytics_bbox`); a folder with no folder_name mapping is returned by
its directory path.
The folder vocabulary is resolved per request from the caller's identity: where the
model_type migration is active for that caller the names are model_type folder_names
(e.g. `ultralytics_bbox`), and a folder with no folder_name mapping is returned by its
directory path. An authenticated response can therefore differ from an anonymous one.
operationId: getModelFolders
responses:
"200":
@@ -2479,7 +2682,10 @@ paths:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security: []
security:
- ApiKeyAuth: []
- BearerAuth: []
- {}
summary: Get available model folders
tags:
- file
@@ -2488,6 +2694,10 @@ paths:
description: |
Returns a list of models available in the specified folder.
This is an experimental endpoint that provides enhanced model information.
Accepted folder identifiers are those returned by /api/experiment/models for the same
caller. That vocabulary is request-scoped, so list folders and fetch a folder's models
with the same credentials — a name obtained anonymously may not resolve when
authenticated, and vice versa.
operationId: getModelsInFolder
parameters:
- description: The folder name to list models from
@@ -2518,7 +2728,10 @@ paths:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security: []
security:
- ApiKeyAuth: []
- BearerAuth: []
- {}
summary: Get models in a specific folder
tags:
- file
@@ -3155,6 +3368,74 @@ paths:
summary: Get full job details
tags:
- workflow
/api/jobs/{job_id}/assets:
get:
description: |
Retrieve a paginated list of the assets produced by a specific job,
enriched with the per-output node context (`node_id`, `output_key`,
`output_index`) correlated from the job's execution outputs by content
hash. Unlike `GET /api/assets?job_ids={id}`, this endpoint is scoped to a
single job and carries node-level placement, making it suited to job
output views rather than the general asset browser. Returns an empty
`assets` array for jobs that produced no assets.
operationId: getJobAssets
parameters:
- description: Job identifier (UUID)
in: path
name: job_id
required: true
schema:
format: uuid
type: string
- description: Maximum number of assets to return (1-500)
in: query
name: limit
schema:
default: 20
maximum: 500
minimum: 1
type: integer
- description: Number of assets to skip for pagination
in: query
name: offset
schema:
default: 0
minimum: 0
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/JobAssetsResponse'
description: Success - Job assets returned
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Job not found or does not belong to the user
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: List a job's output assets
tags:
- workflow
/api/jobs/{job_id}/cancel:
post:
description: |
@@ -3360,6 +3641,12 @@ paths:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Payment required - Insufficient credits
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Workspace governance policy blocks one or more partner providers (error.type PARTNER_NODE_DISABLED; error.class_types lists the offending nodes, error.providers the disabled providers)
"413":
content:
application/json:
@@ -3371,7 +3658,7 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Payment required - User has not paid
description: 'Retryable backpressure. Two distinct causes, disambiguated by the body''s `error.type`, NOT by parsing `error.message`: `PAYMENT_REQUIRED` / `FREE_TIER_UNAVAILABLE` / `FREE_TIER_EXHAUSTED` / `PARTNER_NODE_PAYMENT_REQUIRED` (a billing gate - retrying without paying never succeeds), or `QUEUE_LIMIT` (this workspace''s bounded job queue is full - retrying after some queued jobs complete will succeed).'
"500":
content:
application/json:
@@ -5210,6 +5497,8 @@ tags:
name: user
- description: Background task management
name: task
- description: Workspace billing and subscription management
name: billing
- description: Workflow storage and version management
name: workflows
- description: Job queue state and control