GET /intent)。
所需范围
您的 API 密钥除sr:v2:create 和 sr:v2:read 外,还必须包含 media:v2:private-read。当组织启用私有媒体时,Legitmark 会授予此范围。
以下所有调用都使用同一把 leo_ 密钥:
media:v2:private-read 时,私有 CDN 组织的 GET /api/v2/sr/{sr_uuid} 会返回空的 media_url 数组,且 certificate_url 为 null。
集成步骤
与公开合作伙伴 API 相同,只有两处变化:不要调用/intent,并将每条媒体 URL 视为短期有效。
1
创建服务请求
使用
leo_ 密钥和常规请求体调用 POST /api/v2/sr?sides=true&item=true。传入 sides=true&item=true 会在响应中直接返回必需/可选照片列表,上传前无需再请求一次。API 参考: POST /api/v2/sr2
上传照片
对所有面调用一次
POST /api/media/signed-urls/{sr_uuid},然后将每张图片 PUT 到返回的 signed_url。不要调用 GET /intent。3
读取照片
使用同一密钥调用
GET /api/v2/sr/{sr_uuid}?item=true&sides=true。media_url(以及传入 summary=true 时的 summary.thumbnail)是有效约 15 分钟的私有 CDN 签名链接。4
读取证书
使用最新 Get Full SR 返回的
certificate_url。如果收到 Access Denied 或 403,请重新获取。也可以在控制台通过 Download certificate 重新生成。上传照片
不要调用GET https://asset.legitmark.com/intent(以及开发和预发布的资产主机)。该路径写入公开存储桶,无法路由私有组织的上传。
一次请求获取所有面的上传 URL,然后将图片字节 PUT 到每个 URL。
API 参考: POST /api/media/signed-urls/{sr_uuid}
响应
TypeScript SDK 目前仍使用
GET /intent。私有 CDN 组织应通过 HTTP 调用 POST /api/media/signed-urls/{sr_uuid},直到 SDK 更新。浏览器上传(CORS)
如果仓库应用或 Web 应用从浏览器PUT 图片,S3 必须允许该页面的来源。请将所有上传来源告知 Legitmark(精确来源和 https://*.example.com 通配符)。组织中已放行的来源可继续使用。PUT 出现 CORS 错误说明需要添加新来源 — 不要回退到 /intent。
读取照片
使用同一把 API 密钥获取服务请求。media_url 是私有 CDN 主机上的 CloudFront 签名链接。
API 参考: GET /api/v2/sr/{sr_uuid}
- 保留 URL 上的
Expires、Key-Pair-Id和Signature。去掉查询字符串会返回403。 - 传入
summary=true时,summary.thumbnail以同样方式签名。 - 早期测试中的公开
cdn.legitmark.com链接不再提供这些照片。
证书
最新GET /api/v2/sr/{sr_uuid} 返回的 certificate_url 是同一私有主机上的签名 PDF 链接。请使用该 URL。如果收到 Access Denied 或 403,说明签名已过期 — 再次调用 GET 并使用新 URL。
也可以在控制台(https://app.legitmark.com 或开发/预发布应用主机)通过 Download certificate 重新生成新链接。
不要复用之前保存的证书链接。
URL 有效期
签名读取 URL 自签发时起有效 15 分钟(expires_in 默认 900 秒)。
- 不要将签名 URL 持久化或缓存在自己的数据库中。
- 不要把签名 URL 当作长期分享链接写入日志或转发给他人。持有该 URL 的人在过期前都能获取对象。
- 每次需要显示或下载照片或证书时,重新调用
GET /api/v2/sr/{sr_uuid}。 - 过期或未签名的 URL 返回
403。这是预期行为。请获取新的 URL。
state_change 后,如需照片或证书,请再获取 SR。
公开分享页
公开分享页不会显示私有 CDN 组织的照片。这是预期行为。照片和证书仅可通过带密钥的合作伙伴 API 访问。环境
将
{org} 替换为 Legitmark 为您的组织预配的主机名。请使用 API 返回的 URL,不要自行拼接 CDN 主机。
图片要求
与公开工作流程相同:- 格式: JPG/JPEG/PNG
- 尺寸: 最小 600 x 600 像素
- 文件大小: 每张图片最大 5 MB
- 质量: 清晰、光线充足、对焦准确的图片