TransRing 文件转换
按次付费的文件格式转换服务。一次调用转换一个文件，付款后执行，结果以下载形式返回。
- 单次调用价格：9.90 元（人民币）
- 服务地址：https://api.richmax.fun
- 版本：1.0.0
支持的转换（试点范围）
| 源格式 | 目标格式 | 说明 |
|---|---|---|
| heic | jpg | iPhone 照片转通用 JPG |
| png | webp | 质量 80，体积更小 |
| docx | Word 文档转 PDF |
- 单文件，单个文件上限 10 MB。
- 不在上表中的转换会被拒绝（HTTP 400），不要尝试。
调用流程
1. 健康检查（可选）
GET https://api.richmax.fun/health
返回服务状态、当前单价、本次试点支持的转换列表。无需付款。
2. 发起转换（未付款 → 402）
POST https://api.richmax.fun/convert
multipart/form-data，字段：
| 字段 | 必填 | 说明 |
|---|---|---|
| file | 是 | 要转换的文件（二进制） |
| target | 是 | 目标格式：jpg / webp / pdf 之一 |
| job_id | 是 | 调用方生成的幂等键：8–64 位，只允许字母、数字、下划线、连字符 |
未付款时返回 HTTP 402 Payment Required：
- 响应头
amtPaymentLink：支付宝预下单号（amtpp_v1_...），把它交给支付宝 AI 付完成付款。这是支付宝 AI 按量付费（MACHINE_PAY）官方流程的响应头，对应预下单接口alipay.aipay.agent.payment.precreate返回的amt_pre_pay_id。 - 响应体（JSON）：
job_id、target、out_trade_no（商户订单号）、amount（"9.90"）、currency（"CNY"）、resource_id、pay_before（付款截止时间，ISO 8601）、goods_name。
3. 付款
把 amtPaymentLink 的值交给支付宝支付能力（AI 付），用户确认后完成付款，拿到支付凭证。凭证结构（Base64URL 编码后放在请求头里）：
{
"protocol": {
"payment_proof": "<支付宝返回的支付凭证>",
"trade_no": "<支付宝交易号>"
},
"method": {
"client_session": "<买家客户端会话标识，原样透传>"
}
}
4. 携带凭证重试（已付款 → 200）
用同一个 job_id、同一个文件、同一个 target再次 POST /convert，并带上请求头：
Payment-Proof: <Base64URL 编码的凭证 JSON>
服务端验证凭证后执行转换，返回 HTTP 200。验证与履约均调用支付宝官方接口：
- 验付：
alipay.aipay.agent.payment.verify（A2A 商户支付凭证验证）。校验active=true、金额等于本次资源价格（9.90 元）、out_trade_no等于服务端生成的商户订单号、resource_id等于本次请求的资源，且同一trade_no不重复履约。 - 履约确认：资源交付后调用
alipay.aipay.agent.fulfillment.confirm，传入trade_no；失败可重试。
验证通过后返回：
{
"status": "done",
"job_id": "...",
"target": "webp",
"output_name": "xxx.webp",
"output_bytes": 12345,
"elapsed_seconds": 1.2,
"download": "/download/<job_id>"
}
5. 下载结果
GET https://api.richmax.fun/download/<job_id>
返回转换后的文件二进制。任务结果保留 10 分钟（600 秒），过期自动清理，请及时下载。
查询任务状态（可选）
GET https://api.richmax.fun/status/<job_id>
幂等与重试
- 同一个
job_id+ 同一文件 + 同一目标：重复请求会直接返回已有的转换结果，不会重复扣费、不会重复转换。 - 付款后重试：必须用付款前同一个
job_id发起的请求，换新的job_id会被当作新订单要求重新付款。 - 转换失败或凭证无效：返回明确的错误码和 402/400/502，可按提示重试或重新下单。
错误码
| HTTP | 含义 |
|---|---|
| 402 | 需要付款（未付款，或凭证无效/过期） |
| 400 | 请求错误：不支持的转换、文件类型不符、文件头校验失败、job_id 非法 |
| 413 | 文件超过 10 MB |
| 502 | 支付网关暂不可用，稍后重试 |
安全与隐私
- 上传的文件仅用于本次转换：转换完成后删除源文件，结果保留 10 分钟后删除。
- 服务端日志只记录任务元数据（job_id、目标格式、文件大小、耗时），不记录文件内容。
- 全程 HTTPS；不要把文件内容或凭证记录到对话历史之外的任何地方。
退款
如转换失败且已付款，或对结果有异议，请联系服务方申请退款。退款按支付宝原路返回，1% 的渠道费按支付宝规则处理。
