# 媒体资源 API

检索与渲染存储在比特币区块链上的 Stamps 原始内容与解码图像。

> Source: bitcoinuniverseio/stampdex (private application source), stamp media cache, media controller, logo resolver. Applicable release continuous deployment, verify with GET /api/version. Last verified 2026-09-01. Chain bitcoin/mainnet.

> [!NOTE]
> **简体中文官方文档**：说明如何直接从链上交易输出中读取 base64 图像并进行高保真展示。 核心交易规则为非托管模式，买卖双方按标准费率收取服务费，并于比特币主网进行原子结算。



These routes serve bytes, not JSON, and do not count against the API rate limit. They
are the only routes served to any browser origin.

## Routes

| Method | Path | Serves |
| --- | --- | --- |
| GET | `/api/v1/stamps/assets/:file` | Raw stamp bytes, addressed as `<txhash>.<ext>` |
| GET | `/api/v1/stamps/:id/preview` | A rendered preview. `?w=160`, `?w=320`, or `?w=640` returns a bounded WebP thumbnail; without `w` you get the original bytes |
| GET | `/api/v1/src20/logo/:tick` | The token logo, resolved once on the server. 404 when no source has one |

## Example

```bash frame=none
curl -o kevin-thumb.webp \
  "https://stamp.api.bitcoinuniverse.io/api/v1/stamps/1472320/preview?w=320"
```

## Caching

| Route | Header |
| --- | --- |
| Raw assets | `Cache-Control: public, max-age=31536000, immutable` |
| Previews | `Cache-Control: public, max-age=86400, stale-while-revalidate=604800` |

Raw assets are content addressed, so the bytes at a given path never change. Cache them
forever.

Previews honour `If-None-Match` and answer 304. Every media response carries
`Server-Timing: media-cache;desc=hit|miss`, so you can see whether the server cache
answered.

A token logo that no source has answers 404, and that 404 is itself cacheable for an
hour, so a missing logo does not cost a lookup on every page view.

## Why thumbnails matter

Original stamp previews from the index run 60 KB to 900 KB. The `?w=` WebP thumbnails
run 3 KB to 40 KB. Use thumbnails in grids and lists, and the original only in a focused
view.

## Untrusted files are served defensively

A stamp is arbitrary bytes somebody put on Bitcoin. Some of them are HTML or SVG.

- Only common image types are served with their own content type. Anything else is
  served as a generic binary stream, so a browser will not execute it.
- HTML and SVG previews carry a strict content security policy that sandboxes them and
  blocks all outbound requests, scripts, forms, and embedding from other sites.

If you are embedding stamp media in your own product, apply the same care. The bytes
are not yours and were not reviewed by anybody.

## Related

- [Stamps endpoints](/docs-stampdex/zh-cn/api/stamps/)
- [Rate limits](/docs-stampdex/zh-cn/api/rate-limits/)