Mint an asset over existing bytes (dedup fast-path)

Zero-byte fast-path: mints a new asset UUID over a blob the platform already has, identified by its blake3 hash.

Trust boundary: resolves only against blobs the platform itself ingested and hashed, and only those the calling account is authorized to use — the client hash is a lookup key, never an authority to register new content. A miss and “exists but not yours” are deliberately indistinguishable (404 blob_not_found).

POST /api/v2/assets/from-hash

Mint an asset over existing bytes (dedup fast-path)

cURL

curl --request POST \
  --url http://127.0.0.1:8189/api/v2/assets/from-hash \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "hash": "blake3:9f8a1c0d...",
  "file_path": "photo.png",
  "tags": [
    "<string>"
  ],
  "expires_in": 86400
}
'

200

{
  "id": "9f8a1c0d-2b3e-4f56-8a7b-1c2d3e4f5a6b",
  "hash": "blake3:9f8a1c0d...",
  "size_bytes": 4816293,
  "content_type": "image/png",
  "created_at": "2023-11-07T05:31:56Z",
  "url": "<string>",
  "url_expires_at": "2023-11-07T05:31:56Z",
  "file_path": "photo.png",
  "created_new": true,
  "expires_at": "2023-11-07T05:31:56Z",
  "job_id": "<string>",
  "job_metadata": {
    "client": "acme"
  }
}

授权

Authorization · string · header · 必填

Authorization: Bearer <credential>. The credential is one of: an account-scoped API key (comfyui-…), accepted on Cloud and serverless; a Comfy Cloud session JWT; or an OAuth access token issued for the Comfy Cloud resource. Which kinds a given deployment accepts is deployment configuration — an API key always works on Cloud and serverless, and a deployment that does not accept JWT bearers answers 401 with a message saying so. Self-hosted accepts unauthenticated requests by default and can be configured with a static bearer token.

请求体

application/json

hash · string · 必填

示例:

"blake3:9f8a1c0d..."

file_path · string

示例:

"photo.png"

tags · string[]

expires_in · integer

Optional retention override in seconds (60s–7d): the asset's expires_at becomes now + expires_in, replacing the platform's default retention. Implementations without configurable retention ignore it. The bounds apply to this override only — the platform default is operator-configured and may lie outside them.

必填范围: 60 <= x <= 604800

示例:

86400

响应

200

application/json

An identical reference already existed; returned as-is.

A user-owned record identified by a server-assigned UUID, backing an immutable blob whose content carries a server-computed blake3 hash. hash may be computed lazily: an asset record (and its retrievable bytes) can exist before its hash is filled in. On an output, job_metadata carries the labels its producing job was submitted with, so code holding only the asset knows which run it came from. It is absent for assets no job produced, for outputs of a job sent without labels, where the serving surface keeps no job labels, and when the labels could not be read: so job_id without job_metadata does not prove the job had no labels. A create whose file path and bytes match an existing output answers with that output, so its job_id and job_metadata are the output's.

id · string · 必填

示例:

"9f8a1c0d-2b3e-4f56-8a7b-1c2d3e4f5a6b"

hash · string | null · 必填

blake3:<hex>; null while lazily computed.

示例:

"blake3:9f8a1c0d..."

size_bytes · integer<int64> · 必填

示例:

4816293

content_type · string · 必填

示例:

"image/png"

created_at · string<date-time> · 必填

url · string<uri> · 必填

Short-lived content URL (signed, or proxy-served).

url_expires_at · string<date-time> · 必填

file_path · string | null

示例:

"photo.png"

created_new · boolean

On create responses: distinguishes a brand-new blob (true) from a dedup hit against bytes the platform already had (false).

expires_at · string<date-time> | null

Retention deadline for the asset itself (distinct from url_expires_at, the signed URL's validity). Null or absent means the asset is non-expiring. On a dedup-hit create response the deadline may be later than now + the requested/default retention: re-referencing content extends its retention, never shortens it.

job_id · string | null

ID of the job that produced this asset. Absent for assets no job produced, such as a fresh upload.

job_metadata · object

The labels the producing job was submitted with, read through job_id on each read. Absent for assets no job produced, for outputs of a job sent without labels, where the serving surface keeps no job labels, when the job is gone, and when the labels could not be read: so job_id without job_metadata does not prove the job had no labels.

Show child attributes

示例:

{ "client": "acme" }