picem

YOUR APPS’ MEDIA HOME

Pic ’em.
Keep ’em.

让每一个文件，
都有一个好去处。

图片、附件、视频。上传一次，接入你的每一个 App。
留住原件，轻快交付。

打开媒体库 ↗用 API 接入 →

Made for your apps. Ready for your agents.

PICEM / COLLECTIONKEEP THE ORIGINAL.
THE BIG PICTURE original preserved
▶   MP4IN MOTION ready to play
↳
everything-else.pdf私有附件 · 按需分享
↗
一份原件。
刚好的每一种尺寸。
一个简单的过程
Upload→Process→Deliver
复杂的部分，交给 Picem。

SMALL API. BIG POSSIBILITIES.

你的下一张图片，
只差一个请求。

统一的资产 ID、可查询的处理状态，
以及无需猜测的 API。

从第一个上传开始 →
upload.sh
curl "$PICEM_URL/v1/assets" \
  -H "Authorization: Bearer $PICEM_API_KEY" \
  -H "Idempotency-Key: my-first-image" \
  -F "file=@photo.jpg" \
  -F "purpose=image" \
  -F "visibility=public"
一个 asset_id，连接你的所有后续操作。
↗

刚好的图片

头像、缩略图和大图各就其位。保留原件，不牺牲后续的可能。

▶

顺手的视频

上传后云端转码，处理完成便是 MP4 和封面。状态随时可查。

⌘

Agent 也会用

OpenAPI、纯文本指南和配套 Skill。接入步骤清楚，失败也有下一步。

YOUR COLLECTION

媒体库.

BUILD SOMETHING GOOD.

少一点接线。
多一点创造。

从一张图片开始。Picem 负责保存、处理与交付，你专注于自己的 App。

快速开始

在工作台创建 App 和 API key，把 key 保存在应用服务端。浏览器只使用后端签发的短期上传地址，不能包含长期 key。

API 地址：
所有 API 响应都包含 X-Request-ID，便于排查问题。

上传一张图片

curl
202 表示已受理，按 status_url 查询，直到 status=ready。返回的尺寸和大小来自实际保存文件。响应的 id 是应该长期保存在业务数据库中的标识。
大文件直接上传 OSS
调用 POST /v1/upload-sessions，提交文件名、大小、用途与可见性。将返回的 fields 与文件一起，以 multipart POST 发到返回的 URL，成功后调用会话的 complete_url。当前版本支持单次直传；网络中断时重新上传同一会话，分片断点续传尚未开放。
通用上传默认私有。用途可选 avatar、image、attachment、video。实际限制以 capabilities 为准。
私有，不只是一个标签。
私有文件没有永久公开链接。App 后端验证用户业务权限后，调用 POST /v1/assets/{id}/access，以 {"variant":"original","expires_in":300} 取得临时链接。最长 15 分钟；不要把它当作永久链接保存。
API key 只访问自己的 App。删除与修改需额外 scope。已签发链接在到期前仍可能可用；公开文件的外部副本无法收回。
上传，然后等它 ready。
以 purpose=video 上传。Picem 使用阿里云 IMS 转码并生成封面；查询资产即可了解状态。完成后使用 playback-mp4 与 poster。原件独立保留，转码失败不丢文件。
目前默认最高 1080p，保留比例、不放大。单文件不超过 1 GB，时长不超过 30 分钟。
状态清楚，重试才靠谱。
validating → processing → ready
失败会有稳定的 error_code。上传重试沿用同一 Idempotency-Key；同键不同参数返回 409。429 应退避；401 检查 key；422 检查文件。不要在网络超时后立刻换键重复上传。
unknown_outcome 代表云任务结果需要对账，不能盲目重提交。删除是异步操作：先停止新访问授权，再清理已发布对象与缓存。
给 Agent 的入口。
下载 Skill 后安装到工作区 .agents/skills/picem/。配置 PICEM_URL 和 PICEM_API_KEY，即可按文档上传、查询和获取链接。Skill 不包含你的凭证。
下载 Picem Skill ↓AI 文档索引 ↗



WELCOME BACK
打开你的媒体工作台。
使用部署时保存在凭证管理位置的管理员凭证。


ADD TO YOUR COLLECTION
选好文件，剩下交给 Picem。




YOUR APP’S KEY
只显示这一次。
保存到 App 服务端的秘密配置。不要放进前端代码。