screenRIG
登录开始使用

API 参考

广告 API

私有广告网络和广告活动

HTTP 参考。 由后端契约生成。浏览以下端点或下载 OpenAPI。

OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览

此分组有 46 个操作，由 api/openapi.yaml 生成。可按路径、操作或认证筛选。每个端点都会列出其输入；展开后可查看请求模板和响应代码。模板需要您自己的值和符合架构的请求体。

用你的值替换大写占位符。对于JSON请求，请保存符合request.json模式的请求体。Cookie示例使用经过身份验证会话的本地Cookie存储。

私有广告网络和广告活动

GET/api/advertising/network

获取广告网络

呼叫卖方的一个网络，包括其已解决的 ScreenRig 服务费。卖方无法更改该费用。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingNetwork

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/network'

响应

状态含义正文和头部
200网络。AdvertisingNetwork（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/network

创建广告网络

若不存在，则创建调用卖方的一个网络。需要 screens=true。幂等；重复调用返回相同网络。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingNetworkCreate
操作 ID
createAdvertisingNetwork

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。

请求主体字段

字段描述
名称（必填，字符串）maxLength：120
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/network'

响应

状态含义正文和头部
200网络。AdvertisingNetwork（application/json）
403禁止 - 项目缺少屏幕功能或计划未知。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/network/rate

设置广告默认费率

设置卖方项目每完成播放 15 秒的默认费率。更改影响已接受广告活动的有效费率时，会暂停整个活动并标记 price_change_pending；掩码或无操作更改不影响。If-Match 带网络修订版本。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingRate
操作 ID
setAdvertisingDefaultRate

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。

请求主体字段

字段描述
rate_mcr_per_15s（必填，McrString）精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。模式："^-?[0-9]+$"
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/network/rate'

响应

状态含义正文和头部
200已更新网络。AdvertisingNetwork（application/json）
412revision_conflict - If-Match 已过期。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/inventory

列出广告库存

呼叫卖方选择加入的库存。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingInventory

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/inventory'

响应

状态含义正文和头部
200库存。AdvertisingInventoryList（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
PUT/api/advertising/inventory/{screen_id}

放置广告库存

更新或插入一个自有屏幕的库存。验证屏幕所有权。费率覆盖为 null 表示恢复继承，而不是零。改变已接受活动有效费率的更改会暂停该活动。受保护屏幕文件夹中的屏幕为 protected_target（409）。

身份验证
projectBearer
请求主体
AdvertisingInventoryWrite
操作 ID
putAdvertisingInventory

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
screen_id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段描述
impressions_per_hour （可选，内联）

卖家对此屏幕每小时所产生展示次数的估算。每次完成的播放会将此值乘以其秒数再除以 3600，在报告中计为估算展示次数。null 或缺省表示没有估算。

ads_enabled（必填，布尔值）
site_name（可选，字符串）maxLength：120
city（可选，字符串）maxLength：120
region（可选，字符串）maxLength：120
venue_type（可选，字符串）maxLength：64
audience_tags（可选，数组）
投放位置（可选，字符串）maxLength：120
public_description（可选，字符串）maxLength：500
rate_override_mcr_per_15s（可选，内联）Null 恢复继承自项目默认；绝不表示零。
请求模板和响应
shell · 请求模板
curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/inventory/SCREEN_ID'

响应

状态含义正文和头部
200已存储的库存。AdvertisingInventory（application/json）
403forbidden - 该屏幕不属于此项目；限定屏幕范围的调用方返回 outside_screen_scope 或 approver_required。问题 (application/problem+json)
409

protected_target - 该屏幕位于受保护屏幕文件夹中，且此更改没有审核表单（docs/screen-scope.md）；通过审核清除该文件夹的保护，完成更改，再次保护该文件夹。

问题 (application/problem+json)
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/slots

列出广告时段

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingSlots

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/slots'

响应

状态含义正文和头部
200插槽。AdvertisingSlotList（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/slots

创建广告位

创建一个可重复使用的卖方广告位。图片时长为 5-30 秒，视频最长为平台上限 120 秒。广告始终静音。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingSlotWrite
操作 ID
createAdvertisingSlot

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。

请求主体字段

字段描述
名称（必填，字符串）minLength：1 maxLength：120
启用（可选，布尔值）
accepted_media（必填，数组）
max_image_duration_ms（必填，整数）最小值：5000 最大值：30000
max_video_duration_ms（必填，整数）最小值：1000 最大值：120000
rate_override_mcr_per_15s（可选，内联）
vast_tag_url（可选，内联）

卖方自有的 VAST 2-4 广告标签，当无邀请活动填充该卖方自有屏幕的插槽时尝试。仅限 HTTPS，端口 443 或 8443，且为公共主机。

后端获取它，跟进最多五个 Wrapper，将选定的渐进式 MP4 或 WebM 媒体文件导入项目媒体，并在接受开始时触发 Impression、creativeView 和 start，接受完成时触发 complete，失败时触发 Error。不触发四分之一追踪器。

宏 [CACHEBUSTING]、[TIMESTAMP]、[SCREENRIG_SCREEN_ID]、[SCREENRIG_SLOT_ID] 和 [SCREENRIG_PAGE_ID] 会被展开。插槽必须支持视频。空值、缺失或空字符串会清除标签。买家永远看不到它。

请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/slots'

响应

状态含义正文和头部
201插槽插槽。AdvertisingSlot（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/slots/{id}

更新广告时段

更新一个卖方广告位。If-Match携带广告位修订版本。费率覆盖变更重新检查定价约束。可选Idempotency-Key在24小时内为相同广告位、请求体和If-Match重放最初已提交的结果，即使之后有编辑。修改内容后重复使用返回idempotency_mismatch。新的过期写入返回revision_conflict。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingSlotWrite
操作 ID
updateAdvertisingSlot

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段描述
名称（必填，字符串）minLength：1 maxLength：120
启用（可选，布尔值）
accepted_media（必填，数组）
max_image_duration_ms（必填，整数）最小值：5000 最大值：30000
max_video_duration_ms（必填，整数）最小值：1000 最大值：120000
rate_override_mcr_per_15s（可选，内联）
vast_tag_url（可选，内联）

卖方自有的 VAST 2-4 广告标签，当无邀请活动填充该卖方自有屏幕的插槽时尝试。仅限 HTTPS，端口 443 或 8443，且为公共主机。

后端获取它，跟进最多五个 Wrapper，将选定的渐进式 MP4 或 WebM 媒体文件导入项目媒体，并在接受开始时触发 Impression、creativeView 和 start，接受完成时触发 complete，失败时触发 Error。不触发四分之一追踪器。

宏 [CACHEBUSTING]、[TIMESTAMP]、[SCREENRIG_SCREEN_ID]、[SCREENRIG_SLOT_ID] 和 [SCREENRIG_PAGE_ID] 会被展开。插槽必须支持视频。空值、缺失或空字符串会清除标签。买家永远看不到它。

请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/slots/RESOURCE_ID'

响应

状态含义正文和头部
200已更新时段。AdvertisingSlot（application/json）
409idempotency_mismatch.问题 (application/problem+json)
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/memberships

列出广告会员

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingMemberships

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/memberships'

响应

状态含义正文和头部
200成员资格。AdvertisingMembershipList（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/memberships/{id}

更新广告会员

显式卖方政策/范围编辑。此处更改活动成员资格，绝不通过发送第二个邀请。范围更改停止新选择；财务历史保留。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingMembershipScope
操作 ID
updateAdvertisingMembership

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。

请求主体字段

字段描述
策略（必填，字符串）允许值：“trusted”、“review_required”
screen_ids（必填，数组）
slot_ids（必填，数组）
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/memberships/RESOURCE_ID'

响应

状态含义正文和头部
200已更新会员。AdvertisingMembership（application/json）
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/memberships/{id}/revoke

撤销广告会员资格

撤销一个成员资格。停止该网络的新选择；不会清除广告主标志、其他成员资格或已结算的历史记录。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
revokeAdvertisingMembership

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/memberships/RESOURCE_ID/revoke'

响应

状态含义正文和头部
200已撤销的成员身份。AdvertisingMembership（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/networks

列出加入的广告网络

调用广告主当前所属的网络，及其授予的范围和审核策略。屏幕计数不保证为展示次数。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingJoinedNetworks

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/networks'

响应

状态含义正文和头部
200已加入的网络。AdvertisingJoinedNetworkList（application/json）
403禁止 - 项目缺少广告主标志。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/networks/{seller_project_id}/inventory

列出加入的广告库存

调用者成员内的已选择库存和可重用时段。绝不暴露卖方的屏幕截图、播放列表或项目范围数据。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingJoinedInventory

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
seller_project_id路径必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/networks/SELLER_PROJECT_ID/inventory'

响应

状态含义正文和头部
200允许的库存和时段。AdvertisingJoinedInventory（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/creatives

列出广告创意

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingCreatives

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/creatives'

响应

状态含义正文和头部
200创意集。AdvertisingCreativeList（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/creatives

创建广告创意

将一个准备好的拥有媒体修订绑定到不可变创意。不复制字节，不重新上传，也不重新计费生成。未知或未准备好的媒体被拒绝。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingCreativeCreate
操作 ID
createAdvertisingCreative

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段描述
media_id（必填，字符串）
copy（可选，字符串）maxLength：500
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/creatives'

响应

状态含义正文和头部
201创意。AdvertisingCreative（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/creatives/{id}

获取广告创意

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingCreative

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/creatives/RESOURCE_ID'

响应

状态含义正文和头部
200创意。AdvertisingCreative（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/seller-campaigns

列出卖方广告活动

调用卖方已提交的买方广告活动，包括没有播放的广告活动，以及买方访问权限被撤销后的历史记录。按标识符顺序最多返回 100 个广告活动。草稿、其他网络和买方整体预算为私有。用 after 跟随 next_after，直到它不再出现。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingSellerCampaigns

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
after查询可选前一页的 next_after。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/seller-campaigns'

响应

状态含义正文和头部
200此卖方网络上已提交的买方广告活动。AdvertisingSellerCampaignList（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/seller-campaigns/{id}

获取卖方广告活动

一个已提交买方广告活动的只读卖方视图。库存和累计已结算的投放仅涵盖调用卖方。买方整体财务和其他网络为私有。无关的卖方会收到 not_found。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingSellerCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/seller-campaigns/RESOURCE_ID'

响应

状态含义正文和头部
200卖方的广告活动和投放详情。AdvertisingSellerCampaignDetail（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/campaigns

列出广告活动

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingCampaigns

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns'

响应

状态含义正文和头部
200广告活动。AdvertisingCampaignList（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/campaigns

创建广告活动

创建一个草稿广告活动。草稿不持有资金，不保留资源，也不授权投放。激活需要明确接受的报价。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingCampaignDraft
操作 ID
createAdvertisingCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。

请求主体字段

字段描述
名称（必填，字符串）minLength：1 maxLength：120
category (可选, AdvertisingCategory)

广告主类别。同一类别的两则广告不会在屏幕的同一个广告时段内播放；没有类别的广告不会被分隔。

允许值: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"

daily_cap_mcr（必填，McrString）精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。模式："^-?[0-9]+$"
lifetime_cap_mcr（必填，McrString）精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。模式："^-?[0-9]+$"
image_duration_ms（可选，整数）广告活动范围内的图片停留时间。视频保持其服务器验证的时长。默认：10000 最小值：5000 最大值：30000
max_play_price_mcr（可选，内联）正的最大完成播放价格。省略表示无额外上限。
flight_start（必填，字符串）格式：“date-time”
flight_end（必填，字符串）格式：“date-time”
网络（必填，数组）
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns'

响应

状态含义正文和头部
201草稿广告活动。AdvertisingCampaign（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/campaigns/{id}

获取广告活动

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID'

响应

状态含义正文和头部
200广告活动。AdvertisingCampaign（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/campaigns/{id}

更新广告活动

更新草稿广告活动。If-Match 携带广告活动版本。预算减少至已支出加已承诺预订之下时，拒绝并使用允许的最小值。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingCampaignDraft
操作 ID
updateAdvertisingCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。

请求主体字段

字段描述
名称（必填，字符串）minLength：1 maxLength：120
category (可选, AdvertisingCategory)

广告主类别。同一类别的两则广告不会在屏幕的同一个广告时段内播放；没有类别的广告不会被分隔。

允许值: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"

daily_cap_mcr（必填，McrString）精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。模式："^-?[0-9]+$"
lifetime_cap_mcr（必填，McrString）精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。模式："^-?[0-9]+$"
image_duration_ms（可选，整数）广告活动范围内的图片停留时间。视频保持其服务器验证的时长。默认：10000 最小值：5000 最大值：30000
max_play_price_mcr（可选，内联）正的最大完成播放价格。省略表示无额外上限。
flight_start（必填，字符串）格式：“date-time”
flight_end（必填，字符串）格式：“date-time”
网络（必填，数组）
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID'

响应

状态含义正文和头部
200已更新广告活动。AdvertisingCampaign（application/json）
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/campaigns/{id}/quote

报价广告活动

在激活前对广告活动当前有效的费率、格式、时长、投放期和上限进行定价。报价有时间限制，任何定价生成或有效费率变更后报价即失效。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
quoteAdvertisingCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/quote'

响应

状态含义正文和头部
201报价。AdvertisingQuote（application/json）
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/campaigns/{id}/activate

激活广告活动

显式接受命名的当前报价并激活广告活动。原子检查所有权、成员资格、报价过期、费率修订、接受范围及同项目拒绝，然后记录购买条款。接受条款不扣钱包余额，不产生卖方收入。相同密钥和正文可重放；正文更改视为冲突。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingQuoteAccept
操作 ID
activateAdvertisingCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段描述
quote_id（必填，字符串）
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/activate'

响应

状态含义正文和头部
200活跃或待审核的广告活动。AdvertisingCampaign（application/json）
409quote_stale 或 self_deal 或 resource_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/campaigns/{id}/pause

暂停广告活动

暂停此广告活动的新预订。已开始的有效广告正常完成并按完成计费。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
pauseAdvertisingCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/pause'

响应

状态含义正文和头部
200广告活动已暂停。AdvertisingCampaign（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/campaigns/{id}/resume

恢复广告活动

恢复手动暂停的广告活动。无法清除 price_change_pending 阻塞；充值、计划触发或卖方操作无法提供该同意。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
resumeAdvertisingCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/resume'

响应

状态含义正文和头部
200广告活动已恢复。AdvertisingCampaign（application/json）
409price_change_pending - 请先接受当前费率。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/campaigns/{id}/accept-rates

接受广告费率

买方明确接受变更的有效费率，绑定报价 ID、广告活动版本和当前定价代。原子替换未来交付条款，记录执行者和时间，清除粘性价格变更阻塞。另一次并发费率变更导致广告活动暂停。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingQuoteAccept
操作 ID
acceptAdvertisingRates

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。

请求主体字段

字段描述
quote_id（必填，字符串）
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/accept-rates'

响应

状态含义正文和头部
200已重新激活广告活动。AdvertisingCampaign（application/json）
409price_change_pending 或 quote_stale。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/reviews

列出广告评论

提交给调用卖方审核的创意版本。卖方仅见提交的创意，绝不见买方库。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingReviews

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews'

响应

状态含义正文和头部
200审核。AdvertisingReviewList（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/reviews/{id}/approve

批准广告审核

批准一项精确提交的创意版本。批准不选择买方预算或授予其媒体库访问权限。人员必须能够批准审核（approver_required）。同一审核也可作为类型 ad_creative 在 /api/reviews. 下访问。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
approveAdvertisingReview

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/approve'

响应

状态含义正文和头部
200审核已批准。AdvertisingReview（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/reviews/{id}/reject

拒绝广告审核

以买方可读的原因拒绝一条具体提交的创意修订。必须有人能批准审核（approver_required）。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingReviewRejection
操作 ID
rejectAdvertisingReview

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填

请求主体字段

字段描述
原因（必填，字符串）minLength：1 maxLength：500
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/reject'

响应

状态含义正文和头部
200审核被拒绝。AdvertisingReview（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/reports/spend

获取广告支出

买家范围内的单个广告活动支出和投放计数。金额为十进制 mcr 字符串。绝不暴露卖家的收入、银行状态或项目范围使用情况。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingSpend

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
格式查询可选json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
campaign_id查询必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reports/spend?campaign_id=CAMPAIGN_ID'

响应

状态含义正文和头部
200花费报告。AdvertisingSpendReport（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/reports/delivery

获取广告投放

卖方范围内的毛额、服务费和净额，针对一个窗口，带有其自身的交付证据。它永远不会暴露买方的钱包或其他网络。只有授权的已完成播放证据才能建立可计费的交付。窗口最长为 92 天；更宽的窗口是 invalid_request。

当持有超过 5000 个结算时，响应设置为截断，总计和计数仍涵盖全部，行仅列出最早的 5000 个。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingDelivery

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
格式查询可选json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
起始查询必填
至查询必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reports/delivery?from=FROM&to=TO'

响应

状态含义正文和头部
200投递报告。AdvertisingDeliveryReport（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/direct-campaigns

列出广告直接活动

调用方卖方的直接广告活动，按最新在前排列，含其进度。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listAdvertisingDirectCampaigns

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns'

响应

状态含义正文和头部
200直接广告活动列表。AdvertisingDirectCampaignList (application/json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/direct-campaigns

创建广告直接活动

在卖方自己的广告库存上预订直接广告活动，即卖方与外部广告主达成的交易。不涉及资金往来；由卖方向广告主结算，价格记录下来用于报告的价值。该活动立即生效，并先于市场活动填充。

有目标的活动在其投放期内按进度均匀投放，落后于进度时优先播放；没有目标的活动在投放期内占用每个符合条件的广告位。同一类别的两则广告不会在屏幕的同一个广告时段内播放。目标超过可用量估算时，除非 overbook 为 true，否则以 goal_overbooked 拒绝。

相同的键加相同的请求体会重放；请求体变化则为冲突。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingDirectCampaignDraft
操作 ID
createAdvertisingDirectCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
Idempotency-Keyheader必填

请求主体字段

字段描述
名称（必填，字符串）minLength：1 maxLength：200
advertiser (必填, string)minLength：1 maxLength：200
category (可选, AdvertisingCategory)

广告主类别。同一类别的两则广告不会在屏幕的同一个广告时段内播放；没有类别的广告不会被分隔。

允许值: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"

flight_start（必填，字符串）格式：“date-time”
flight_end（必填，字符串）格式：“date-time”
goal_plays (可选, integer)要投放的播放次数，在投放期内按进度均匀投放。为零或省略表示占用投放期内每个符合条件的广告位。minimum: 0 maximum: 1000000000000
price (可选, AdvertisingDirectPrice)卖方记录的交易价格。screenRIG 从不收取该费用；它用于计算报告的价值。
media_ids (必填, array)卖方已就绪的图片和视频，每个只列出一次。
image_duration_ms（可选，整数）广告活动范围内的图片停留时间。视频保持其服务器验证的时长。默认：10000 最小值：5000 最大值：30000
screen_ids (可选, array)为空表示每个已加入的屏幕。
slot_ids (可选, array)为空表示每个已启用的广告位。
venue_types (可选, array)
cities (可选, array)
tags (可选, array)
dayparts (可选, array)
overbook (可选, boolean)预订超过可用量估算的目标。不设置时请求以 goal_overbooked 拒绝。default: false
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/direct-campaigns'

响应

状态含义正文和头部
201直接广告活动。AdvertisingDirectCampaign (application/json)
402feature_not_in_plan — 项目的计划不包含直接广告活动；required_plan 指明包含它的计划。问题 (application/problem+json)
409goal_overbooked 或 resource_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/direct-campaigns/{id}

获取广告直接活动

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingDirectCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID'

响应

状态含义正文和头部
200直接广告活动。AdvertisingDirectCampaign (application/json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/direct-campaigns/{id}

更新广告直接活动

替换活动的草稿字段。If-Match 携带活动的修订版本。已投放的播放次数予以保留。仍需投放的播放次数会对照可用量估算进行检查，其中不计入该活动自身的预订，overbook 则照常预订。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingDirectCampaignDraft
操作 ID
updateAdvertisingDirectCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。

请求主体字段

字段描述
名称（必填，字符串）minLength：1 maxLength：200
advertiser (必填, string)minLength：1 maxLength：200
category (可选, AdvertisingCategory)

广告主类别。同一类别的两则广告不会在屏幕的同一个广告时段内播放；没有类别的广告不会被分隔。

允许值: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"

flight_start（必填，字符串）格式：“date-time”
flight_end（必填，字符串）格式：“date-time”
goal_plays (可选, integer)要投放的播放次数，在投放期内按进度均匀投放。为零或省略表示占用投放期内每个符合条件的广告位。minimum: 0 maximum: 1000000000000
price (可选, AdvertisingDirectPrice)卖方记录的交易价格。screenRIG 从不收取该费用；它用于计算报告的价值。
media_ids (必填, array)卖方已就绪的图片和视频，每个只列出一次。
image_duration_ms（可选，整数）广告活动范围内的图片停留时间。视频保持其服务器验证的时长。默认：10000 最小值：5000 最大值：30000
screen_ids (可选, array)为空表示每个已加入的屏幕。
slot_ids (可选, array)为空表示每个已启用的广告位。
venue_types (可选, array)
cities (可选, array)
tags (可选, array)
dayparts (可选, array)
overbook (可选, boolean)预订超过可用量估算的目标。不设置时请求以 goal_overbooked 拒绝。default: false
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID'

响应

状态含义正文和头部
200已更新的直接广告活动。AdvertisingDirectCampaign (application/json)
402feature_not_in_plan — 项目的计划不包含直接广告活动；required_plan 指明包含它的计划。问题 (application/problem+json)
409goal_overbooked 或 resource_conflict。问题 (application/problem+json)
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/direct-campaigns/{id}/pause

暂停广告直接活动

停止活动中的活动产生新的播放。已投放的播放次数和投放期予以保留。已暂停或已结束的活动会返回 resource_conflict。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
pauseAdvertisingDirectCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID/pause'

响应

状态含义正文和头部
200已暂停的直接广告活动。AdvertisingDirectCampaign (application/json)
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/direct-campaigns/{id}/resume

恢复广告直接活动

恢复已暂停的直接广告活动。暂停期间落后于进度的有目标活动优先播放，直到追上进度。活动中或已结束的活动会返回 resource_conflict。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
resumeAdvertisingDirectCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID/resume'

响应

状态含义正文和头部
200已恢复的直接广告活动。AdvertisingDirectCampaign (application/json)
402feature_not_in_plan — 项目的计划不包含直接广告活动；required_plan 指明包含它的计划。问题 (application/problem+json)
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/direct-campaigns/{id}/end

结束广告直接活动

在投放期结束前结束一个活动中或已暂停的活动。已结束的活动不再播放，并保留其报告。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
endAdvertisingDirectCampaign

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID/end'

响应

状态含义正文和头部
200已结束的直接广告活动。AdvertisingDirectCampaign (application/json)
412revision_conflict。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/direct-campaigns/{id}/report

获取广告直接活动报告

一个直接广告活动在某个时间窗口内的投放情况，含其进度、已投放播放次数的记录价值，以及按 UTC 日、屏幕、广告位和媒体划分的行。不带 from 和 to 时，窗口为整个投放期。窗口内的行数超过报告所列时，响应设置 truncated，合计仍涵盖每一次播放。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingDirectCampaignReport

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
格式查询可选json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
id路径必填
起始查询可选
至查询可选
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID/report'

响应

状态含义正文和头部
200直接广告活动报告。AdvertisingDirectReport (application/json)
402feature_not_in_plan — 项目的计划不包含直接广告活动；required_plan 指明包含它的计划。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/availability

估算广告可用量

估算直接目标在给定库存和投放期内可预订的播放次数。这是只读操作，不更改任何内容。估算值是目标屏幕近期广告位出现次数按投放期推算的结果，再减去同一批屏幕上其他直接广告活动仍需的目标。

身份验证
projectBearer 或 dashboardSession
请求主体
AdvertisingAvailabilityQuery
操作 ID
estimateAdvertisingAvailability

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。

请求主体字段

字段描述
screen_ids (可选, array)为空表示每个已加入的屏幕。
slot_ids (可选, array)为空表示每个已启用的广告位。
venue_types (可选, array)
cities (可选, array)
tags (可选, array)
dayparts (可选, array)
flight_start（必填，字符串）格式：“date-time”
flight_end（必填，字符串）格式：“date-time”
exclude_campaign_id (可选, string)编辑时，将此直接广告活动自身的预订从 booked_plays 中排除。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/availability'

响应

状态含义正文和头部
200可用量估算。AdvertisingAvailability (application/json)
402feature_not_in_plan — 项目的计划不包含直接广告活动；required_plan 指明包含它的计划。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/reports/fill

获取广告填充统计

调用方卖方在窗口内的广告位供给，按UTC日和总计列出。每次出现由直接广告活动、市场广告活动或VAST标签填充，或带有原因保持未填充。请求窗口最长35天，默认为过去7天。供给精确到小时。

完整包含与请求的半开时间窗口重叠的所有UTC小时；from向下取整、to向上取整到UTC小时边界。已对齐的to仍是排他上界。响应返回这些有效边界，范围可达35天加1小时。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingFillStats

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
格式查询可选json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
起始查询可选
至查询可选
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reports/fill'

响应

状态含义正文和头部
200填充统计。AdvertisingFillStats (application/json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/reviews/{id}

获取广告审核

卖方网络某次审核的详细信息。返回审核和确切提交的创意版本。绝不暴露买方的其他媒体。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingReview

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID'

响应

状态含义正文和头部
200审核及其创意。AdvertisingReviewDetail（application/json）
404not_found - 卖家未知该评论。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/advertising/reviews/{id}/content

获取广告审核内容

仅流传该卖方自身审核所指的精确创意版本。所有权归买方项目；不公开对象键或签名位置，且无法访问其他买方媒体。ETag 为创意的强 SHA-256，审核期间不变。

控制台会话响应为 private, no-cache，浏览器保存一份副本并重新验证；项目持有者响应为 private, no-store。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getAdvertisingReviewContent

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
范围header可选V1 仅接受一个字节范围。
If-None-Matchheader可选此路由返回的强创意 SHA-256 ETag。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/content'

响应

状态含义正文和头部
200审核的精确创意字节。无正文；头部：Accept-Ranges、Content-Length、ETag、Cache-Control
206一个符合标准的字节范围。无正文；头部：Content-Range、ETag、Cache-Control
304创意的 ETag 与 If-None-Match 匹配，在卖方项目审核解决后检查。不产生主体或出口增量。无正文；头部：ETag、Cache-Control
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
HEAD/api/advertising/reviews/{id}/content

广告审核内容头部

身份验证
projectBearer
请求主体
无
操作 ID
headAdvertisingReviewContent

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
范围header可选V1 仅接受一个字节范围。
请求模板和响应
shell · 请求模板
curl --request HEAD --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/content'

响应

状态含义正文和头部
200仅元数据。无正文；头部：Content-Length、ETag
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/advertising/reviews/{id}/request-changes

请求广告审核更改

卖方向买方请求对已提交创意版本的更改。审核变为 changes_requested，理由中带备注；买方在创意上查看，下一次审核时，活动为该卖方打开，链接 previous_review_id。必须有人能批准审核（approver_required）。

身份验证
projectBearer 或 dashboardSession
请求主体
ReviewChangesRequest
操作 ID
requestAdvertisingReviewChanges

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填

请求主体字段

字段描述
备注（必填，字符串）minLength：1 maxLength：500
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/request-changes'

响应

状态含义正文和头部
200审核，状态为 changes_requested。AdvertisingReview（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)