ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 06 · Assets and dependencies / 上传
Canonical map: https://zzd.show/docs/ai/map.json
Full handbook: https://zzd.show/llms-full.txt
REST capabilities: https://zzd.show/api/v1/capabilities/

# Assets, uploads, and dependencies

Upload source-specific project assets; use pinned public CDNs only
for appropriate shared libraries.

## Choose the right asset surface

- Photo: managed raster/thumbnail-like visual assets.
- Upload: video, audio, model, font, JSON, code support, binary, and
  general files.
- StaticFileBinding: an explicit attachment of an uploaded file to a
  Show with a stable mount path and semantic role.
- `cdns` / `esm`: pinned shared browser libraries and module maps,
  not a dumping ground for source-specific media.

Scoped REST v1 exposes one safe byte-upload route:
`POST /api/v1/shows/{show_id}/assets/`. It accepts exactly one
allowlisted non-executable file plus a safe relative `mount_path`,
`role`, and short `context`; it creates the owned Upload and binding
together and returns the stable
`/assets/show/{show_id}/{mount_path}` URL. It does not fetch URLs,
accept web documents/scripts, replace an occupied mount path, or
delete an asset.

Developer-uploaded draft bytes remain in opaque private storage
outside public media. The stable mount URL is Show-access/session
checked for a draft owner and returns private/no-store bytes; it is
not an asset bearer endpoint, and there is no raw private-root URL.
Confirmed publication promotes a public copy. A later draft-producing
Show mutation or unpublish removes the promoted copy while retaining
the private source so the same mount path can be republished safely.

A separate verified-cover route is available at `POST
/api/v1/shows/{show_id}/thumbnail/`; it accepts exactly one decoded,
non-animated JPEG, PNG, or WebP and returns the Show to draft. An
owner with `shows:read` can stream the private cover through `GET
/api/v1/shows/{show_id}/thumbnail/content/`. That GET is the only
bearer byte-delivery route in this asset workflow and returns
private/no-store content without revealing storage names.

Direct upload, upload-from-URL, text-upload, replacement, and delete
helpers may be present in the signed-in editor. They are not REST v1
routes. The current UI upload-from-URL policy allows at most 50 MB
per fetched
file, applies basic unsafe/private-network target checks, and shares
an aggregate account storage cap currently set to 1 GB. Prefer direct
upload. Fetch only user-approved public HTTP(S) assets; never use
credential-bearing or signed private URLs, and do not treat redirect
handling as a complete security boundary. Treat the UI/response as
authoritative because limits may evolve. Never bypass size, MIME,
ownership, SSRF, or quota checks.

For REST v1 the current limits are 50 MiB per safe uploaded asset and
1 GiB aggregate account storage, with the live capabilities response
authoritative. Use a versioned new mount path when maintenance needs
a new file, or use the signed-in editor after impact review.

## Asset manifest

Keep a compact project manifest with:

- semantic role and useful description/alt/context;
- original project-relative path when applicable;
- resulting ZZD asset reference;
- media/type/codec;
- runtime consumers;
- binding mount path and role, if bound;
- license/rights note where needed.

Enumerate more than static `<img>` tags: CSS `url()`, fonts,
`srcset`, posters, dynamic imports/fetches, GLTF buffers/textures,
Draco decoders, shaders, workers, wasm, Lottie/Rive, HLS segments,
audio, frame sequences, and state-revealed assets. Audit the network
after loader, scroll, click, hover, drag, route, and media changes.

Replace local-machine, temporary, signed, and source-host URLs with
ZZD-managed references. Preserve distinct URL identity when a loader
caches or mutates resources by URL. Patch the smallest source-owned
URL builder rather than globally rewriting network traffic.

Do not upload `.env`, credentials, private keys, source-control
metadata, private datasets, server configuration, analytics beacons,
trackers, or irrelevant build caches. Do not hotlink source-specific
media. Do not expose storage internals in Pieces or prompts.

Validation must include MIME and actual decodability. For example,
a browser may fetch a video successfully and still reject its codec;
a model file may return 200 and still have an invalid binary header.
Inspect rendered `currentSrc`, natural dimensions, media state, model
load completion, and errors after real interaction.