VxReels App API 接口参考

原始 Markdown:/docs/raw

# VxReels App API 接口参考

更新日期:2026-10-10。按当前 Worker 实现核对;上游代理接口的业务字段和校验由对应服务维护。示例不代表每个模型、支付流程或真实 Meta 投递均已线上验收。

## 1. 基本信息

Shortpress Visitor API 是 Visitor App 的 Cloudflare Worker BFF。

生产地址:

- `https://api.vxreels.site`

本地开发地址:

```text
http://127.0.0.1:8790
```

除代理上游返回其他 Content-Type 的情况外,JSON 响应通常包含:

```http
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
```

## 2. 接口总览

| 方法 | 路径 | 类型 | 鉴权 |
|------|------|------|------|
| GET, HEAD | `/` | 健康入口 | 否 |
| GET, HEAD | `/docs/app-api` | App 接入文档 | 否 |
| GET, HEAD | `/docs/website-api` | 后台接口要求 | 否 |
| GET, HEAD | `/api/client/site/bundle` | 固定发现入口代理 | 无需 Token,GET 需 X-App-Id |
| GET, HEAD | `/docs` | 本地文档 | 否 |
| GET, HEAD | `/docs/raw` | 本地文档 | 否 |
| GET, HEAD | `/api/create-page/config` | 分流配置 | 否 |
| GET, HEAD | `/api/home/tabs` | 本地数据 | 否 |
| GET, HEAD | `/api/home/trending` | 分流 Feed | 否 |
| GET, HEAD | `/api/home/new` | 分流 Feed | 否 |
| GET, HEAD | `/api/home/top_rated` | 分流 Feed | 否 |
| GET, HEAD | `/api/home/most_favorited` | 分流 Feed | 否 |
| GET, HEAD | `/api/home/short` | 分流 Feed | 否 |
| POST | `/api/home/template/generate` | 本地组装后代理 | Token |
| GET | `/api/app/update/check` | D1 | 设备上下文 |
| POST | `/api/ads/facebook/events` | 本地 CAPI | Token |
| GET, HEAD | `/api/payment/coins/package/list` | 代理 | 建议 Token |
| GET, HEAD | `/api/payment/subscription/package/list` | 代理 | 建议 Token |
| GET, HEAD | `/api/payment/coins/balance` | 代理 | Token |
| POST | `/api/payment/iap/verify` | 代理 | Token |
| POST | `/api/payment/iap/verify-subscription` | 代理 | Token |
| POST | `/api/payment/iap/notify`(兼容 `/api/iap/notify`) | Apple 回调代理 | Apple 签名 |
| POST | `/api/user/login` | 代理 | 否 |
| POST | `/api/user/login/app-code` | 代理 | 否 |
| POST | `/api/user/app-login-code` | 代理 | Token |
| POST | `/api/user/register` | 代理 | 否 |
| GET, HEAD | `/api/user/profile` | 代理 | Token |
| POST | `/api/user/change-password` | 代理 | Token |
| POST | `/api/user/delete-account` | 代理 | Token |
| GET, HEAD | `/api/plugins/video/query` | 代理 | Token |
| POST | `/api/plugins/video/generate` | 代理 | Token |
| GET, HEAD | `/api/client/creations` | 代理 | Token |
| DELETE | `/api/client/creations/{taskId}` | 代理 | Token |
| POST | `/api/client/upload` | 代理 | 否(Token 可选透传) |

通用代理透传登录 Token,由上游验证。Facebook 事件接口先检查 Bearer 头,再请求上游 profile 验证身份。`GET /` 返回 `{"ok":true,"service":"app-api-vxreels"}`。

业务代理接口通常使用统一响应信封:

```json
{
  "code": 0,
  "info": "ok",
  "data": {}
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 业务状态码,`0` 通常表示成功 |
| `info` | string | 状态或错误说明 |
| `data` | any | 接口业务数据 |

## 3. 公共请求头

| Header | 格式 | 用途 |
|--------|------|------|
| `X-Device-Context` | base64url JSON | 分流与 App 更新检查 |
| `Authorization` | `Bearer <accessToken>` | 用户、支付、IAP、视频和上传 |
| `X-App-Id` | iOS Bundle ID,如 `com.vx.reels` | 动态发现业务上游、生成上游及站点 |
| `X-Site-Id` | UUID/字符串 | 可省略;传入时必须与 Bundle 查询结果一致 |
| `X-Locale` | 如 `en`、`zh-CN` | 透传给上游 |
| `X-App-Version` | 如 `1.0.4` | 透传给上游 |
| `CF-Connecting-IP` | IPv4 | Cloudflare 注入的客户端 IP |
| `X-Debug-IP` | IPv4 | 本地调试 IP 覆盖 |

生产配置使用 `BUNDLE_LOOKUP_URL` 作为固定发现入口。携带 `X-App-Id` 的业务、生成、首页和创作配置请求,先查询 Bundle 对应的 `apiDomain`、`videoApiDomain`、`siteId`。两个域名分别组装为 `https://{domain}/app-upstream`,站点 ID 自动填入上游请求。请求中的 `X-Site-Id`、`siteId`、`site_id` 如与发现结果冲突,返回 403。

成功配置按“发现入口 + Bundle ID”在边缘缓存 60 秒;未知 Bundle 返回 404,重复绑定返回 409,发现服务故障或响应配置不完整返回 502,不回退到其他站点。未配置发现入口或未携带 `X-App-Id` 的旧请求保留默认上游行为。D1 更新检查及静态文档、首页 Tab 不依赖发现服务。

### GET /api/client/site/bundle

无需登录,必须携带 `X-App-Id`,不需要 `X-Site-Id`。此接口始终访问固定发现入口,不递归查找、不使用上述路由缓存。

```bash
curl https://api.vxreels.site/api/client/site/bundle -H 'X-App-Id: com.vx.reels'
```

```json
{"code":0,"info":"ok","data":{"apiDomain":"api.vxreels.com","videoApiDomain":"video.vxreels.com","siteId":"80de3f91-5295-4731-ac33-8893ad3f400c"}}
```

现有创作模型配置和 D1 绑定仍由此 Worker 管理,动态路由并不自动替换它们。

## 4. X-Device-Context

Header 是紧凑 JSON 的 base64url 编码结果。

编码前示例:

```json
{
  "v": 1,
  "ts": 1787760000000,
  "ap": {
    "v": "1.0.3",
    "b": "42",
    "p": "ios",
    "id": "com.example.visitor"
  },
  "dev": {
    "em": 0,
    "jb": 0,
    "vpn": 0
  },
  "adj": {
    "net": "Facebook Ads",
    "camp": "campaign-1"
  }
}
```

字段说明:

| 字段 | 类型 | 说明 |
|------|------|------|
| `v` | number | 上下文协议版本,必填 |
| `ts` | number | 时间戳,必填;当前服务端不校验有效期 |
| `ap.v` | string | App 版本 |
| `ap.b` | string | build number |
| `ap.p` | string | `ios` 或 `android` |
| `ap.id` | string | Bundle ID 或 Android 包名 |
| `dev.em` | `0|1` | `1` 表示模拟器 |
| `dev.jb` | `0|1` | `1` 表示越狱或 Root |
| `dev.vpn` | `0|1|null` | VPN 状态,当前不参与分流 |
| `adj.net` | string | Adjust network |
| `adj.camp` | string | Adjust campaign |
| `adj.grp` | string | Adjust ad group |
| `adj.cre` | string | Adjust creative |
| `dbg.ip` | string | 调试 IP,当前优先于真实客户端 IP |

无效的设备上下文在普通分流接口中按“无设备信息”处理;在更新检查接口中返回 HTTP 400。

## 5. Organic / Ad 分流

以下接口使用流量分流:

- `/api/create-page/config`
- `/api/home/trending`
- `/api/home/new`
- `/api/home/top_rated`
- `/api/home/most_favorited`
- `/api/home/short`

`/api/create-page/config` 和全部 `/api/home/*` Feed 都先应用 `TRAFFIC_MODE`。固定模式 `0`、`1` 直接返回,不查询用户资料;只有动态模式 `2` 才在请求携带 `Authorization: Bearer <accessToken>` 时查询 `/api/user/profile`。动态模式下 `premiumType >= 1` 返回 ad,并设置 `X-Traffic-Reason: vip_user`。无 Token、非 VIP、Token 无效或资料服务暂时不可用时,继续执行基础规则。

`TRAFFIC_MODE`:

| 值 | 结果 |
|----|------|
| `0` | ad |
| `1` | organic |
| `2` | 动态分类 |

Create Page 与 Home Feed 分类优先级:

1. `TRAFFIC_MODE=0`:`ad`,`TRAFFIC_MODE=1`:`organic`;
2. 动态模式下,已登录且 `premiumType >= 1`:`ad / vip_user`;
3. 动态模式下 IP 命中 organic CIDR:`organic / ip_organic`;
4. App 版本高于 D1 最新版本:`organic / app_version_newer`;
5. 模拟器或越狱/Root:`organic / emulator_or_rooted`;
6. Adjust 广告归因:`ad / adjust_ad`;
7. 其他情况:`organic / adjust_organic`。

动态模式响应头示例:

```http
X-Traffic-Variant: ad
X-Traffic-Reason: adjust_ad
```

> 注意:设备上下文目前没有签名,调用方可以构造相关字段。分流结果不应作为鉴权或付费权限判断依据。

## 6. 通用错误

### 404 未找到

```json
{
  "error": "not_found"
}
```

### 405 方法不允许

```json
{
  "error": "method_not_allowed"
}
```

### 502 上游不可用

```json
{
  "error": "upstream_unavailable"
}
```

代理接口通常保留上游 HTTP 状态码和响应体。只有 fetch 抛出异常时,通用代理才生成 `upstream_unavailable`。

## 7. 文档接口

### GET /docs

返回内嵌的 HTML 文档页。

```bash
curl https://api.vxreels.site/docs
```

`GET|HEAD /docs/app-api` 提供 App 接入文档;`GET|HEAD /docs/website-api` 提供后台接口要求。

### GET /docs/raw

返回内嵌的 Markdown 文档。

```bash
curl https://api.vxreels.site/docs/raw
```

两个接口都支持 HEAD,HEAD 固定返回 HTTP 200 且无响应体。

## 8. Create Page

### GET /api/create-page/config

根据分流结果返回对应创作页 JSON 原文。

请求示例:

```bash
curl -H "X-Device-Context: <base64url-context>" \
  https://api.vxreels.site/api/create-page/config
```

响应结构:

```json
{
  "defaults": {
    "creationParams": {},
    "defaultTab": "imageToVideo",
    "defaultModelByTab": {}
  },
  "modes": {}
}
```

可通过以下字段验证分流:

| 字段 | organic | ad |
|------|---------|----|
| `defaults.defaultModelByTab.imageToVideo` | `ViduQ2` | `Spicy3Ultimate` |
| `defaults.defaultModelByTab.textToVideo` | 无 | `A4` |

HEAD 会执行分流并返回流量 Header,但不返回配置响应体。

## 9. Home

### GET /api/home/tabs

返回固定 Tab 列表。

响应示例:

```json
{
  "tabs": [
    {
      "name": "Trending",
      "endpoint": "/api/home/trending",
      "description": "热门列表"
    },
    {
      "name": "New",
      "endpoint": "/api/home/new",
      "description": "最新列表"
    },
    {
      "name": "Top Rated",
      "endpoint": "/api/home/top_rated",
      "description": "高评分列表"
    },
    {
      "name": "Most Favorited",
      "endpoint": "/api/home/most_favorited",
      "description": "最多收藏列表"
    },
    {
      "name": "Short",
      "endpoint": "/api/home/short",
      "description": "短视频列表(duration ≤ 5 秒)"
    }
  ]
}
```

### GET /api/home/{feed}

`feed` 可取:

- `trending`
- `new`
- `top_rated`
- `most_favorited`
- `short`

Query 参数:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `page` | 正整数 | `1` | 仅用于响应元数据,不做真实分页 |
| `perPage` | 正整数 | `30` | 实际随机返回最多 12~16 条;不足时返回全部有效条目 |

请求示例:

```bash
curl "https://api.vxreels.site/api/home/trending?page=1&perPage=30"
```

organic 响应示例:

```json
{
  "feed": "trending",
  "page": 1,
  "perPage": 14,
  "total": 80,
  "maxReached": true,
  "data": [
    {
      "vid": "video-id",
      "title": "Example",
      "username": "Shortpress",
      "modelName": "Example",
      "isPublic": true,
      "isVip": false,
      "price": 0,
      "keywords": [],
      "cover": "https://example.com/cover.jpg",
      "local_path": "https://example.com/video.mp4",
      "input_img": "",
      "modelRating": 5,
      "status": 2,
      "duration": 5,
      "config": {
        "coin": 0,
        "effectId": "",
        "templateType": ""
      }
    }
  ]
}
```

现有分流判为 ad 且 `X-App-Id: com.vxshort.app` 时,五个 Home Feed 请求 `https://playbox.veloxreel.com/api/explore/{feed}`,仅透传 `page` / `perPage`,保留上游状态码与响应体;不向公开 Playbox 发送用户 Token、Cookie、App 网关凭据或其他客户端请求头。Playbox 不可用时返回 502,分流结果仍为 ad。

organic 及其他 App 的 ad 继续请求 Bundle 对应业务后台的 `/api/client/site/plist?site_id=<siteId>&orderType=0&page=1&pageSize=80`。仅取每个列表首个已发布(`status=2`)、有视频地址和封面的条目;保留模板类型,不伪装成 Clip。时长优先取上游正数,否则为 5 秒;`short` 仅包含时长 ≤5 秒条目。`maxReached=true`;评分和热门排序为展示用估算,非真实统计榜单。

实际 HEAD 行为:Home Feed 的 HEAD 请求直接返回本地 HTTP 200,不访问上游、不执行流量分类,也不包含流量 Header。它不保证与 GET 状态一致。

### POST /api/home/template/generate

使用 Home Feed 返回的完整 `item` 和用户上传后的图片 URL 创建视频。请求必须带 `Authorization: Bearer <accessToken>` 与 `X-App-Id: com.vx.reels`;`X-Site-Id` 可省略。

```json
{
  "item": {
    "vid": "video-id",
    "local_path": "https://cdn.example.com/template.mp4",
    "duration": 8,
    "config": {
      "effectId": "effect-id",
      "templateType": "vidu"
    }
  },
  "imageUrl": "https://cdn.example.com/upload/person.jpg"
}
```

Worker 根据 `item` 生成受控的上游请求,客户端不需要也不能通过此接口指定 `model` 或价格:

| `item` 类型 | 判定字段 | 上游模型 | 必需字段 |
|-------------|----------|----------|----------|
| 普通 dance 模板 | `config.templateType=dance` | `aitubo_dance` | `vid`、`config.effectId` |
| 普通 vidu 模板 | `config.templateType=vidu` | `aitubo_template` | `vid`、`config.effectId` |
| 普通 spicy 模板 | `config.templateType=spicy` | `sora_template` | `vid`、`config.effectId` |
| 公开参考视频 Clip | 未提供 `config.templateType` | `Spicy3Clip` | `vid`、`local_path`;必须能在本站公开 plist 中找到同 ID 且无模板类型的条目 |

Clip 分支会重新查询公开 plist,使用服务端视频 URL 和时长构造 `args.image_url`、`video_url`、`template_video_id`、`video_time`、固定提示词及 `speedup=false`;`video_id=""`、`number=1`。时长向上取整,构造器无有效时长时默认 8 秒。未找到公开参考视频返回 400,查询失败返回 502。模板类型决定模型,不由流量标签决定。

成功响应为现有 `/api/plugins/video/generate` 的原始响应,保存其中的 `data.task_id` 和 `data.model`,再调用查询接口。请求 JSON 无效、字段缺失或模板类型不支持时返回 HTTP 400:

```json
{
  "error": "invalid_request",
  "message": "item.vid 不能为空"
}
```

## 10. App 更新检查

### GET /api/app/update/check

从 `X-Device-Context.ap` 读取平台、Bundle ID、版本号和 build number,然后查询 D1 最新 published 发版。

请求示例:

```bash
curl -H "X-Device-Context: <base64url-context>" \
  https://api.vxreels.site/api/app/update/check
```

无效上下文:

```http
HTTP/1.1 400 Bad Request
```

```json
{
  "error": "invalid_device_context"
}
```

没有对应发版:

```http
HTTP/1.1 404 Not Found
```

```json
{
  "error": "release_not_found"
}
```

存在更新:

```json
{
  "updateAvailable": true,
  "forceUpdate": true,
  "release": {
    "version": "1.0.4",
    "buildNumber": 44,
    "forceUpdate": true,
    "storeUrl": "https://apps.apple.com/app/id0000000000",
    "downloadUrl": null,
    "updateUrl": "https://apps.apple.com/app/id0000000000",
    "updateKind": "store",
    "releaseNotes": "Bug fixes"
  }
}
```

无需更新:

```json
{
  "updateAvailable": false,
  "forceUpdate": false,
  "release": null
}
```

当前判定规则:

- 只比较版本号前三段;
- 客户端 build number 不参与是否更新判断;
- `min_version`、`min_build_number` 不参与强制更新判断;
- Android 优先使用 `downloadUrl`;
- iOS 只使用 `storeUrl`;
- 该接口不支持 HEAD。

## 11. Payment

支付接口代理到 Bundle 查询结果的 `https://{apiDomain}/app-upstream`。生产无需静态配置 `PAYMENT_BASE_URL`。

### GET /api/payment/coins/package/list

金币套餐列表。

Query:

| 参数 | 必填 | 说明 |
|------|------|------|
| `siteId` | 否 | 缺失时使用 Worker 默认 site ID |

请求体:无。鉴权:不需要。

Worker 会同时向上游发送 `siteId` 和 `site_id`,并设置:

```http
X-Client-Platform: ios
```

响应 `data[]` 字段:

| 字段 | 类型 | 说明 |
|------|------|------|
| `packageId` | string | 套餐 ID |
| `name` | string | 套餐名称 |
| `description` | string | 套餐说明 |
| `features` | JSON | 功能卖点列表或结构化配置,可能省略 |
| `coinAmount` | integer | 金币数量 |
| `price` | number/string | 当前价格;具体 JSON 表示由服务端 Money 类型决定 |
| `originalPrice` | number/string | 原价,可能省略 |
| `currency` | string | 货币代码 |
| `discountPercentage` | integer | 折扣百分比,可能省略 |
| `status` | integer | `1` 为启用;客户端接口只返回启用套餐 |
| `iosProductId` | string | App Store 商品 ID |

### GET /api/payment/subscription/package/list

订阅套餐列表,Query、站点 ID 补齐和平台 Header 行为与金币套餐相同。请求体和鉴权均不需要。

响应 `data[]` 字段:

| 字段 | 类型 | 说明 |
|------|------|------|
| `packageId` | string | 套餐 ID |
| `siteId` | string | 所属站点 ID |
| `name` | string | 套餐名称 |
| `description` | string | 套餐说明 |
| `interval` | string | 计费周期,如 `weekly`、`monthly`、`yearly` |
| `price` | number/string | 当前价格;具体 JSON 表示由服务端 Money 类型决定 |
| `originalPrice` | number/string | 原价,可能省略 |
| `currency` | string | 货币代码 |
| `discountPercentage` | integer | 折扣百分比,可能省略 |
| `coins` | integer | 套餐赠送金币数量 |
| `rights` | JSON | 订阅权益配置 |
| `status` | integer | `1` 为启用;客户端接口只返回启用套餐 |
| `iosProductId` | string | App Store 商品 ID |
| `createdAt` | integer | 创建时间戳 |

### GET /api/payment/coins/balance

查询金币余额。

| 参数位置 | 参数 | 必填 | 说明 |
|----------|------|------|------|
| Header | `Authorization` | 是 | `Bearer <accessToken>` |
| Header | `X-Site-Id` | 否 | 携带 X-App-Id 时从 Bundle 配置填入站点 ID |
| Query | `siteId` | 否 | Worker 会转换并同时向上游补 `siteId`、`site_id` |

请求体:无。

```bash
curl -H "Authorization: Bearer <accessToken>" \
  "https://api.vxreels.site/api/payment/coins/balance?siteId=<siteId>"
```

成功响应 `data` 字段:

| 字段 | 类型 | 说明 |
|------|------|------|
| `balance` | integer | 当前金币余额 |
| `totalEarned` | integer | 累计获得金币 |
| `totalSpent` | integer | 累计消费金币 |
| `totalRealMoneySpent` | number/string | 累计真实货币消费金额 |

### POST /api/payment/iap/verify

iOS 金币购买验证。

请求头:

```http
Authorization: Bearer <accessToken>
X-App-Id: com.vx.reels
Content-Type: application/json
```

请求体:

```json
{
  "transactionId": "2000000123456789",
  "account": "apple",
  "packageName": "com.example.visitor",
  "packageId": "server-package-id"
}
```

请求体字段:

| 字段 | 类型 | iOS 必填 | 说明 |
|------|------|----------|------|
| `transactionId` | string | 是 | Apple StoreKit 交易 ID |
| `account` | string | 是 | 支付渠道标识,iOS 使用 `apple` |
| `packageName` | string | 客户端约定传入 | App Bundle ID;Google 校验时是包名 |
| `packageId` | string | 是 | 服务端数据库套餐 ID,不是 App Store Product ID |
| `purchaseToken` | string | 否 | Google Play purchase token;iOS 不使用 |

服务端 Handler 没有为这些字段声明 Gin `binding:"required"`,因此“iOS 必填”表示业务成功所需字段,而不是 JSON 绑定阶段的强校验。

成功响应:

```json
{
  "code": 0,
  "info": "ok",
  "data": {
    "productId": "app-store-product-id"
  }
}
```

上游 `code === 0` 后,Worker 会在后台(`waitUntil`)用 Conversions API 上报 `Purchase`,`eventId` 为 `transactionId`。验单响应形状不变;CAPI 失败不影响发货。

### POST /api/payment/iap/verify-subscription

iOS 订阅购买验证,请求头、请求体及字段含义与金币验证相同。

成功响应 `data`:

| 字段 | 类型 | 说明 |
|------|------|------|
| `isActive` | boolean | 订阅当前是否有效 |
| `sandbox` | boolean | 是否为沙盒交易 |
| `isInFreeTrial` | boolean | 是否处于免费试用期 |
| `autoRenewStatus` | boolean | 是否开启自动续订 |

订阅验单成功后,Worker 同样会后台上报 CAPI `Purchase`(`contentCategory=subscription`)。

### POST /api/payment/iap/notify

Apple App Store Server Notifications 回调,兼容路径 `POST /api/iap/notify`。
在 App Store Connect 的 App Store Server Notifications V2 设置中配置回调 URL(生产和沙盒按需分别配置);这是 Apple 服务端调用的接口,无需 App 主动调用:

| 已部署域名 | 回调 URL |
|---|---|
| VxReels | `https://api.vxreels.site/api/payment/iap/notify` |
| VxShort | `https://api.vxshort.site/api/payment/iap/notify` |

注意:两个地址都固定转发到 VxReels 上游,不会自动切换到 `api.vxshort.com`。使用前需确保通知中的 Bundle ID 已在该上游正确配置。

- 无需 `Authorization`、`X-App-Id`、`X-Site-Id`,不查询 Bundle 配置。
- 请求体为 Apple 的 `{"signedPayload":"<Apple JWS>"}`,原样转发,由上游验签和处理通知。
- 固定上游为 `https://api.vxreels.com/api/iap/notify?account=apple`,没有 `/app-upstream` 前缀;所有 Worker 域名下该路由均指向此上游,不根据 App ID 切换站点。
- 仅转发 Content-Type 和原始正文,不转发用户凭据或调用方查询参数,不触发 Worker 的 Facebook Purchase 上报。
- 保留上游 HTTP 状态和正文,禁止缓存;网络错误或 15 秒等待超时返回 HTTP 502 `upstream_unavailable`,不伪装成功。非 POST 返回 405。
- Worker 不验证或解码 JWS;签名验证、通知幂等及业务处理由上游负责。

2026-10-10 已验证两个域名及兼容路径:无效 `signedPayload` 均返回与上游相同的 HTTP 401 `Invalid Apple signature`;主路径 GET 返回 405。114 项本地测试及类型检查通过。此结果仅证明转发和错误处理,真实 Apple 通知、续订及退款业务尚未联调。

### Payment 上游映射

| Worker 路径 | 上游路径 |
|-------------|----------|
| `/api/payment/coins/package/list` | `/api/client/payment/coins/package/list` |
| `/api/payment/subscription/package/list` | `/api/client/payment/subscription/package/list` |
| `/api/payment/coins/balance` | `/api/client/payment/coins/balance` |
| `/api/payment/iap/verify` | `/api/iap/verify` |
| `/api/payment/iap/verify-subscription` | `/api/iap/verifysub` |
| `/api/payment/iap/notify`、`/api/iap/notify` | 固定绝对地址 `https://api.vxreels.com/api/iap/notify?account=apple` |

Payment GET 接口的 HEAD 请求直接返回本地 HTTP 200,不访问上游。

## 12. User

### App 登录码

`POST /api/user/app-login-code` 生成登录码,需要当前网页用户的 `Authorization: Bearer <token>`、`X-App-Id: com.vx.reels`(站点由发现接口填入),请求体为 `{"appId":"com.vx.reels"}`。

`POST /api/user/login/app-code` 使用登录码登录,无需用户 Token,请求体为 `{"loginCode":"<六位登录码>"}`。携带同一 `X-App-Id`;显式 X-Site-Id 必须与生成登录码时的站点及 Bundle 配置一致。

两个接口均转发到同名上游路径,保留请求体及 `Authorization`、`X-Site-Id`、`X-App-Id`、`X-IOS-Proof` 等请求头。是否要求 App 身份证明由上游配置决定。上游响应状态和正文原样返回,并禁止缓存。

### POST /api/user/login

请求 Header:

| 参数 | 必填 | 说明 |
|------|------|------|
| `X-Site-Id` | 否 | 上游要求站点 ID;携带 X-App-Id 时 Worker 从 Bundle 配置填入 |

请求体字段:

| 字段 | 类型 | 必填 | 校验 |
|------|------|------|------|
| `email` | string | 是 | 必须符合邮箱格式 |
| `password` | string | 是 | 非空;登录接口不额外检查最短长度 |

```json
{
  "email": "user@example.com",
  "password": "123456"
}
```

成功响应:

```json
{
  "code": 0,
  "info": "success",
  "data": {
    "accessToken": "<token>",
    "ver": "1.0.3"
  }
}
```

`ver` 是服务端保存或返回的 App 版本信息。

### POST /api/user/register

请求 Header 与登录相同。请求体字段:

| 字段 | 类型 | 必填 | 校验 |
|------|------|------|------|
| `email` | string | 是 | 必须符合邮箱格式 |
| `password` | string | 是 | 至少 6 个字符 |
| `nickname` | string | 否 | 没有显式长度约束 |

```json
{
  "nickname": "user",
  "email": "user@example.com",
  "password": "123456"
}
```

成功响应 `data`:

| 字段 | 类型 | 说明 |
|------|------|------|
| `accessToken` | string | 注册后签发的访问令牌 |
| `siteId` | string | 当前站点 ID |
| `ver` | string | 请求 `X-App-Version`;缺失时为空字符串 |

### GET /api/user/profile

| 参数位置 | 参数 | 必填 | 说明 |
|----------|------|------|------|
| Header | `Authorization` | 是 | `Bearer <accessToken>` |
| Header | `X-Site-Id` | 否 | 携带 X-App-Id 时 Worker 从 Bundle 配置填入 |

Query 和请求体:无。

```bash
curl -H "Authorization: Bearer <accessToken>" \
  https://api.vxreels.site/api/user/profile
```

成功响应 `data` 字段:

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 用户 ID |
| `email` | string | 邮箱 |
| `nickname` | string | 昵称 |
| `avatarUrl` | string | 头像 URL |
| `premiumType` | integer | `0` 免费,`1` premium;其他值由服务端扩展 |
| `onetimeSub` | integer | `1` 表示一次性订阅 |
| `premiumExpiresAt` | integer | Premium 到期 Unix 时间戳 |
| `autoUnlock` | boolean | 是否自动解锁内容 |
| `status` | integer | 用户状态 |
| `referer` | string | 来源标识 |
| `pixelId` | string | Facebook Pixel ID |
| `loginType` | integer | `0` 邮箱、`1` Google、`2` Facebook、`3` Twitter、`4` TikTok |
| `hasPurchased` | boolean | 是否发生过购买 |
| `ver` | string | App 版本信息 |

HEAD 直接返回本地 HTTP 200,不访问上游。

### POST /api/user/change-password

请求 Header:`Authorization: Bearer <accessToken>`;`X-Site-Id` 缺失时由 Worker 补齐。

请求体字段:

| 字段 | 类型 | 必填 | 校验 |
|------|------|------|------|
| `newPassword` | string | 是 | 6~64 个字符 |

```json
{
  "newPassword": "new-password"
}
```

成功时 `data` 为空对象。

### POST /api/user/delete-account

请求 Header:`Authorization: Bearer <accessToken>`;`X-Site-Id` 缺失时由 Worker 补齐。

Query:无。请求体:无。上游仅根据认证用户执行软删除;即使 Worker 收到请求体,上游 Handler 也不会读取。

成功时 `data` 为空对象。

## 13. Video

视频接口代理到 Bundle 查询结果的 `https://{videoApiDomain}/app-upstream`。生产无需静态配置 `VIDEO_BASE_URL`。

### GET /api/plugins/video/query

Query:

| 参数 | 必填 | 说明 |
|------|------|------|
| `task_id` | 是 | 生成任务 ID |
| `model` | 否 | 与生成请求一致的模型标识;用于预置缓存和响应模型名解析 |

```bash
curl -H "Authorization: Bearer <accessToken>" \
  "https://api.vxreels.site/api/plugins/video/query?model=a2eGenerate&task_id=<taskId>"
```

HEAD 直接返回本地 HTTP 200,不访问视频上游。

成功响应 `data` 的统一字段:

| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | string | 客户端任务 ID |
| `external_task_id` | string | 第三方任务 ID,可能省略 |
| `status` | integer | `1` 处理中、`2` 成功、`3` 失败 |
| `model` | string | 生成模型标识,可能省略 |
| `video_id` | string | 关联业务视频 ID,可能省略 |
| `prompt` | string | 提示词,可能省略 |
| `reference_images` | string[] | 参考图片,可能省略 |
| `videos` | object[] | 视频结果,每项包含 `url`,可能包含 `cover_url` |
| `images` | string[] | 图片结果 URL |
| `error_msg` | string | 失败原因 |
| `retry_count` | integer | 重试次数 |
| `provider_status` | string | 第三方任务状态 |
| `transfer_status` | string | 媒体转存状态 |
| `transfer_retries` | integer | 转存重试次数 |
| `transfer_error` | string | 转存错误 |
| `source_videos` | object[] | 第三方原始视频列表 |
| `delivery_mode` | string | 交付模式 |
| `transfer_retry_at` | string | 下次转存重试时间 |
| `created_at` | string | 创建时间 |
| `updated_at` | string | 更新时间 |

### POST /api/plugins/video/generate

提交视频或图片生成任务。Worker 会解析并兼容部分旧参数,最终业务校验、扣币和生成由上游负责。

请求 Header:

| 参数 | 必填 | 说明 |
|------|------|------|
| `Authorization` | 是 | `Bearer <accessToken>`;上游负责验证身份与权限 |
| `X-Site-Id` | 否 | 携带 X-App-Id 时自动从 Bundle 配置填入;显式值必须一致 |
| `Content-Type` | 是 | `application/json`;Worker 可在缺失时自动补齐 |

通用请求体字段:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 生成器标识,必须是服务端已注册模型 |
| `video_id` | string | 否 | 业务视频/模板 ID;用于计价、扣币和关联记录 |
| `number` | integer | 否 | 生成数量;缺失或 `≤ 0` 按 `1` 计算,总点数为单价乘数量 |
| `args` | object | 是 | 模型参数对象 |

完整请求示例:

```bash
curl -X POST \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-App-Id: com.vx.reels" \
  -H "Content-Type: application/json" \
  -d '{"model":"viduq2_image","video_id":"template-1","number":1,"args":{"image":"https://example.com/input.jpg","prompt":"gentle movement","duration":"5","resolution":"720p"}}' \
  https://api.vxreels.site/api/plugins/video/generate
```

成功响应:

```json
{
  "code": 0,
  "data": {
    "task_id": "client-task-id",
    "model": "viduq2_image"
  }
}
```

模型清单以 `/api/create-page/config` 返回值及生成服务能力为准,不将历史后端注册表视为当前线上可用清单。Worker 对普通生成请求做以下精确兼容:

| App 提交的 model | 转发 model |
|---|---|
| `mulerouter/wan2.2-i2v-spicy` | `Spicy3Pro` |
| `mulerouter/w3.0-video` | `Spicy3Ultra` |
| `mulerouter/w3.0-video-prime` | `Spicy3Ultimate` |

仅对 `viduq2_image`:移除 `args.usedDefaultImage`,将数值型 `args.duration` 转成字符串。其他模型及其参数不做上述修改。App 应直接提交配置要求的字段,不能依赖网关修复任意参数错误。Home 参考视频的 `Spicy3Clip` 是另一个分支,不使用此处普通模型别名。

`args` 是模型相关对象。上游契约中常见字段如下;并非每个模型都支持所有字段:

| 字段 | 类型 | 适用示例 | 说明 |
|------|------|----------|------|
| `prompt` | string | 多数生成模型 | 正向提示词 |
| `negative_prompt` | string | 部分视频模型 | 负向提示词 |
| `image`、`image_url`、`sourceImage` | string | 图生视频、舞蹈 | 输入图片 URL;字段名由模型决定 |
| `images`、`input_images` | string[] | 模板、多图/编辑模型 | 输入图片列表 |
| `duration` | string/number | Vidu、视频模型 | 视频时长;具体类型由模型决定 |
| `video_time` | integer | Ultra 类模型 | 视频时长 |
| `resolution` | string | 多数图片/视频模型 | 分辨率,也会影响部分模型计价 |
| `aspect_ratio`、`ratio` | string | Flux、Vidu、模板模型 | 宽高比 |
| `safety_checker` | boolean/string | Flux、Vidu | 是否启用安全检查;部分实现接受布尔字符串 |
| `num_images` | integer | `flux1.0` | 图片生成数量 |
| `performance` | string | `flux1.0` | 性能档位 |
| `mode` | string | `viduq2_image` | 生成模式 |
| `movement_amplitude` | string | `viduq2_image` | 运动幅度 |
| `generate_audio` | boolean | `viduq2_image` | 是否生成音频 |
| `voice_id` | string | `viduq2_image` | 声音 ID |
| `effectId` | string | `aitubo_template` | 特效/模板 ID |
| `scene` | string | `aitubo_template` | 场景参数 |
| `danceId` | string | `aitubo_dance` | 舞蹈模板 ID |
| `faceEmotion` | boolean | `aitubo_dance` | 是否启用面部表情 |
| `background` | boolean | `aitubo_dance` | 是否保留/生成背景 |
| `template_id` | string | `sora_template` | 必填的 Sora 模板 ID |
| `input` | object | AtlasCloud 模型 | 原样传给 AtlasCloud 的嵌套输入对象 |

Worker 不维护全部生成器的参数 Schema。调用方应以创作页配置构造 `args`,上游的 4xx/5xx 与业务错误会原样返回。

## 14. Creations

### GET /api/client/creations

上游契约为当前登录用户在本站点最近 24 小时的生成记录;保留期限由后台维护。上游:`https://{apiDomain}/app-upstream` 的 `/api/client/creations`。用户归属、保留期限、分页与删除限制由上游实现;Worker 透传请求,不能据此认定其已完成业务授权校验。

请求头:

| 参数 | 必填 | 说明 |
|------|------|------|
| `Authorization` | 是 | `Bearer <accessToken>` |
| `X-Site-Id` | 否 | Worker 缺失时补默认站点 ID |

Query:

| 参数 | 必填 | 说明 |
|------|------|------|
| `page` | 否 | 默认 `1` |
| `pageSize` | 否 | 默认 `20`,最大 `100` |

```bash
curl -H "Authorization: Bearer <accessToken>" \
  "https://api.vxreels.site/api/client/creations?page=1&pageSize=20"
```

HEAD 直接返回本地 HTTP 200,不访问上游。

成功响应 `data`:

| 字段 | 类型 | 说明 |
|------|------|------|
| `items` | object[] | 记录列表 |
| `total` | integer | 总数 |
| `page` | integer | 当前页 |
| `pageSize` | integer | 每页条数 |
| `hasMore` | boolean | 是否还有下一页 |

`items[]` 字段:

| 字段 | 类型 | 说明 |
|------|------|------|
| `taskId` | string | 生成任务 ID |
| `status` | integer | `1` 处理中、`2` 成功、`3` 失败 |
| `model` | string | 生成模型标识 |
| `prompt` | string | 提示词,可能省略 |
| `videos` | object[] | `{ url, coverUrl }`,可能省略 |
| `images` | string[] | 图片结果 URL,可能省略 |
| `errorMsg` | string | 失败原因,可能省略 |
| `createdAt` | integer | Unix 秒 |
| `updatedAt` | integer | Unix 秒 |

### DELETE /api/client/creations/{taskId}

从当前登录用户的创作列表中移除一条记录。只允许删除已结束任务:`status=2`(成功)或 `status=3`(失败);`status=1`(处理中)返回 HTTP 409。删除为软删除,不会删除任务快照、扣费、退款或运营审计记录。

请求头:`Authorization: Bearer <accessToken>`,`X-Site-Id` 可选(Worker 缺失时补默认站点 ID)。路径参数 `taskId` 必填,且必须属于 Token 用户和当前站点。

```bash
curl -X DELETE \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Site-Id: 80de3f91-5295-4731-ac33-8893ad3f400c" \
  -H "Accept: application/json" \
  "https://api.vxreels.site/api/client/creations/<taskId>"
```

Swift 调用示例:

```swift
func deleteCreation(taskId: String, accessToken: String, siteId: String) async throws {
    let encodedTaskId = taskId.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? taskId
    let url = URL(string: "https://api.vxreels.site/api/client/creations/\(encodedTaskId)")!

    var request = URLRequest(url: url)
    request.httpMethod = "DELETE"
    request.setValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")
    request.setValue(siteId, forHTTPHeaderField: "X-Site-Id")
    request.setValue("application/json", forHTTPHeaderField: "Accept")

    let (data, response) = try await URLSession.shared.data(for: request)
    guard let http = response as? HTTPURLResponse else {
        throw URLError(.badServerResponse)
    }
    guard (200...299).contains(http.statusCode) else {
        let message = String(data: data, encoding: .utf8) ?? "删除失败"
        throw NSError(
            domain: "CreationAPI",
            code: http.statusCode,
            userInfo: [NSLocalizedDescriptionKey: message]
        )
    }
}
```

成功:

```json
{ "code": 0, "info": "ok", "data": {} }
```

响应状态:

| HTTP | `code` | 说明 |
|------|--------|------|
| `200` | `0` | 删除成功,记录已从当前用户创作列表隐藏 |
| `401` | `401` | Token 缺失、无效或已过期 |
| `404` | `404` | 任务不存在,或不属于当前 Token 用户/站点 |
| `409` | `409` | 任务仍在处理中,只能删除已结束任务 |

处理中任务响应:

```json
{ "code": 409, "info": "只能删除已结束任务", "data": {} }
```

任务不存在或所有权不匹配:

```json
{ "code": 404, "info": "创作记录不存在", "data": {} }
```

删除成功后,App 应立即从本地列表移除该 `taskId`,或重新请求 `GET /api/client/creations`。不要对 `status=1` 的任务显示删除入口。

## 15. Upload

### POST /api/client/upload

上传文件,使用 multipart/form-data。Worker 保留 multipart Content-Type 和 boundary,并流式转发请求体。上游路由不要求登录,Authorization 和 X-Site-Id 均不是必填参数。

Form Data:

| 字段 | 类型 | 必填 | 约束 |
|------|------|------|------|
| `file` | file | 是 | 恰好一个文件;零个返回 400,多个也返回 400 |

代码和 Swagger 将该接口描述为图片上传,但 Handler 不校验 MIME、扩展名或文件大小,只保留原始扩展名并写入存储目录。实际允许范围还可能受到 Gin、反向代理和部署环境的请求体大小限制。

```bash
curl -X POST \
  -F "file=@example.jpg" \
  https://api.vxreels.site/api/client/upload
```

成功响应:

```json
{
  "code": 0,
  "info": "ok",
  "data": "res/user_upload/<directory>/<filename>.jpg"
}
```

## 16. 完整代理映射

以下根地址来自 Bundle 查询;当前 VxReels 对应 apiDomain=`api.vxreels.com`、videoApiDomain=`video.vxreels.com`。每行路径追加到根地址,勿漏掉 `/app-upstream`。

| Worker 路径 | 默认上游 | 上游路径 |
|-------------|----------|----------|
| `/api/client/site/bundle` | `BUNDLE_LOOKUP_URL`(完整 URL) | 不额外追加路径 |
| `/api/payment/coins/package/list` | `https://{apiDomain}/app-upstream` | `/api/client/payment/coins/package/list` |
| `/api/payment/subscription/package/list` | `https://{apiDomain}/app-upstream` | `/api/client/payment/subscription/package/list` |
| `/api/payment/coins/balance` | `https://{apiDomain}/app-upstream` | `/api/client/payment/coins/balance` |
| `/api/payment/iap/verify` | `https://{apiDomain}/app-upstream` | `/api/iap/verify` |
| `/api/payment/iap/verify-subscription` | `https://{apiDomain}/app-upstream` | `/api/iap/verifysub` |
| `/api/payment/iap/notify`、`/api/iap/notify` | 固定 `https://api.vxreels.com` | `/api/iap/notify?account=apple` |
| `/api/user/login` | `https://{apiDomain}/app-upstream` | `/api/user/login` |
| `/api/user/login/app-code` | `https://{apiDomain}/app-upstream` | `/api/user/login/app-code` |
| `/api/user/app-login-code` | `https://{apiDomain}/app-upstream` | `/api/user/app-login-code` |
| `/api/user/register` | `https://{apiDomain}/app-upstream` | `/api/user/register` |
| `/api/user/profile` | `https://{apiDomain}/app-upstream` | `/api/user/profile` |
| `/api/user/change-password` | `https://{apiDomain}/app-upstream` | `/api/user/change-password` |
| `/api/user/delete-account` | `https://{apiDomain}/app-upstream` | `/api/user/delete-account` |
| `/api/plugins/video/query` | `https://{videoApiDomain}/app-upstream` | `/api/plugins/video/query` |
| `/api/plugins/video/generate` | `https://{videoApiDomain}/app-upstream` | `/api/plugins/video/generate` |
| `/api/home/template/generate` | `https://{videoApiDomain}/app-upstream` | `/api/plugins/video/generate`(Worker 先转换请求体) |
| `/api/client/creations` | `https://{apiDomain}/app-upstream` | `/api/client/creations` |
| `/api/client/creations/{taskId}` | `https://{apiDomain}/app-upstream` | `/api/client/creations/{taskId}` |
| `/api/client/upload` | `https://{apiDomain}/app-upstream` | `/api/client/upload` |

## 17. HEAD 请求说明

HEAD 行为并不完全等同于对应 GET:

| 接口类型 | 实际行为 |
|----------|----------|
| `/docs`、`/docs/raw`、`/docs/app-api`、`/docs/website-api`、`/`、Home Tabs、Bundle 查询 | 本地返回 200,无 body |
| Create Page | 携带 X-App-Id 时先做 Bundle 查询,再执行分流,返回分流 Header,无 body |
| Home Feed | 本地返回 200,不分流、不访问上游 |
| 支付 GET、用户资料、视频查询、创作列表 | 本地返回 200,不访问上游 |
| App 更新检查 | 不支持 HEAD,返回 405 |

因此不能使用代理接口的 HEAD 结果判断上游资源是否存在或上游是否健康。

## 18. 调试示例

### 强制 organic IP

以下 Header 主要适用于本地 Wrangler 调试:

```bash
curl -H "CF-Connecting-IP: 17.1.2.3" \
  http://127.0.0.1:8790/api/create-page/config
```

### Adjust 广告归因

构造包含非 organic network 的设备上下文,然后请求:

```bash
curl -H "X-Device-Context: <encoded-context>" \
  http://127.0.0.1:8790/api/home/trending
```

预期响应头:

```http
X-Traffic-Variant: ad
X-Traffic-Reason: adjust_ad
```

### 查看在线文档

```bash
curl http://127.0.0.1:8790/docs/raw
```

## 19. Facebook Conversions API

Worker 本地处理,不把 Facebook Access Token 返回给客户端。`pixelId` 来自上游 `GET /api/user/profile`,随后用 `FB_PIXEL_API_KEY` 作为 Bearer 凭据调用 `GET {FB_PIXEL_API_BASE_URL}/{pixelId}`,返回的 `token` 仅用于发送到 Meta。默认查询入口为 `https://fb.vxreels.site/api/external/pixels`。`action_source` 固定为 `website`。

密钥(不要写入 `wrangler.jsonc` vars):

```bash
wrangler secret put FB_PIXEL_API_KEY
# staging 测试事件页打开时再设,生产必须为空:
wrangler secret put FACEBOOK_CAPI_TEST_EVENT_CODE
```

`FB_PIXEL_API_KEY` 是 Pixel 管理服务的对外 API Key,不是 Meta Token。App API 不需要绑定该服务的 D1 或持有解密密钥,也不再使用全局 `FACEBOOK_CAPI_ACCESS_TOKEN`。

外部查询成功结构为 `{pixelId, token, websites}`。Worker 验证返回的 `pixelId` 与用户资料一致,Token 非空;5 秒超时,不跟随重定向,不转发 App 用户 Token。每次上报重新查询,不缓存 Token;密钥与查询结果不会返回给 App 或记录到日志。

本地使用测试 API Key(见 `.dev.vars.example`)。事件来源网址优先使用请求的 `eventSourceUrl`;未传时,从 Pixel 查询响应的 `websites` 按顺序取第一个有效 `domain`,转换为 HTTPS 根网址。两处均无有效网址时返回 503,不向 Meta 投递。无需配置事件来源网址环境变量,也没有硬编码站点回退。

### POST /api/ads/facebook/events

鉴权:`Authorization: Bearer <accessToken>`。Worker 用该 token 拉 profile;无 Bearer 或上游认证失败返回 401;profile 网络异常、非成功响应等返回 503。

请求体字段:`eventName`(`PageView` / `Lead` / `InitiateCheckout` / `Purchase`)、`eventId`(Lead / Purchase 必填)、可选 `eventTime`、`eventSourceUrl`、`customData`、`userData`(`clientUserAgent` / `madid` / `anonId`)。

禁止上传:`pixelId`、`accessToken`、`actionSource`、`testEventCode`、明文 `email`。

```bash
curl -sS -X POST http://127.0.0.1:8790/api/ads/facebook/events \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-App-Id: com.vx.reels" \
  -H "Content-Type: application/json" \
  -d '{"eventName":"Lead","eventId":"task-123"}'
```

成功:`{ "code": 0, "info": "ok", "data": { "accepted": true, "eventName": "Lead", "eventId": "task-123", "fbtraceId": "..." } }`。

站点未配置 profile `pixelId` 或 查询接口返回 Pixel 不存在 时返回 HTTP 503 `facebook not configured`;缺失查询 API Key、查询接口鉴权失败/超时或返回不匹配的 Pixel/无效 Token 返回 HTTP 503 `facebook configuration unavailable`。不会返回密文、密钥或底层异常。IAP 验单成功后的服务端 Purchase 使用同一查询逻辑,但配置失败不改变验单响应。

Meta 拒绝事件时返回 HTTP 502,超时返回 504,`data.accepted` 为 `false`,可包含数值型 `upstreamStatus`、`errorCode`、`errorSubcode`;不返回 Meta 原始错误信息或凭据。只有 Meta 确认 `events_received >= 1` 才记录去重成功。当前没有持久化重试队列,不再将失败伪报为 `queued: true`。

去重键为 `pixelId + eventName + eventId`,成功后用 Cache API 缓存 7 天。命中时返回 `data.accepted=true`、`data.deduplicated=true`,不再次向 Meta 投递;未提供 eventId 时不做 Worker 去重。边缘缓存不是持久、全局原子存储,不能保证并发或跨节点严格只投递一次。失败可用相同 eventId 重试。

Meta 请求地址为 `POST https://graph.facebook.com/v26.0/{pixelId}/events`,超时 3 秒。用户邮箱与 ID 经规范化和 SHA-256 后填入 `em`、`external_id`;IP、User-Agent 从请求补充。`customData` 支持非负 `value`(两位小数)、`currency`(默认 USD)、`contentIds`、`contentType`、`contentCategory`。`eventTime` 为 Unix 秒,未提供或早于七天前时改用当前时间。

IAP 成功后通过 `waitUntil` 尝试自动上报 Purchase:使用请求中的 `transactionId` 作为 eventId,`packageId` 作为 contentIds,币种固定 USD,分类为 coins/subscription;当前不读取真实交易金额,不填 value。缺少 transactionId 时不触发。此后台尝试没有持久队列,投递失败不改变 IAP 响应。

测试记录:截至 2026-09-28,已验证 Pixel 查询与错误处理;现有测试 Meta Token 被拒绝(code 190)。尚不能据此宣称真实 Meta 投递验收通过。

测试:Events Manager → 测试事件页保持打开,staging 注入 `FACEBOOK_CAPI_TEST_EVENT_CODE`,确认来源为 Server。生产不要设置该 secret。

## 20. 相关文档

- [项目说明](./project-summary.md)
- [原始接口文档](./api.md)
- [项目 README](../README.md)