在 Roblox 上創建和管理廣告。體驗廣告通過廣告 API 驅動參與度，物品廣告通過贊助活動推廣市場物品。請參閱 [廣告指南](https://create.roblox.com/docs/cloud/guides/advertising) 以獲取 Open Cloud 的設置和使用。

表示廣告創意的模型（例如，廣告縮略圖）。

創意的 ID。通常是縮略圖的 imageId。

廣告創意的類型。通常是 CreativeType.Image。 ['未定義' = 0, '圖像' = 1, '視頻' = 2]

用於檢索 Roblox.AdConfiguration.Api.SponsoredCampaignModel 頁面的回應模型。

檢索下一頁的游標（如果存在）。

檢索上一頁的游標（如果存在）。

Roblox.AdConfiguration.Api.SponsoredCampaignModel 的集合。

活動目標類型 ['未定義' = 0, '宇宙' = 1, '資產' = 2, '沉浸式廣告' = 3]

活動目標的名稱（即資產名稱、宇宙名稱、群組名稱等）

活動/廣告的每日出價金額，以 Robux 計算

放置活動的位置 ['未定義' = 1, '遊戲排序' = 2, '角色商店' = 4, '物品詳細信息' = 8, '首頁' = 16, '廣告牌300x250' = 32, '廣告牌600x300' = 64, '廣告牌300x600' = 128]

廣告集的目標年齡段 ['未定義' = 1, '13歲以下' = 2, '13歲及以上' = 4, '13-16歲' = 8, '17歲及以上' = 16]

廣告集的目標設備類型 ['未定義' = 1, '電腦' = 2, '手機' = 4, '平板電腦' = 8, '遊戲機' = 16, 'VR' = 32]

廣告集的目標性別 ['未定義' = 1, '男性' = 2, '女性' = 4]

返回 Robloكس.AdConfiguration.Api.Models.CampaignTargetModel 的集合的響應模型

獲取或設置 Roblox.AdConfiguration.Api.Models.CampaignTargetModel 的集合

表示停止贊助活動/廣告請求的模型。

我們希望在結果中包含的活動類型列表

一個回應模型，表示一個廣告，包含完整的信息，包括其相關活動和廣告集的信息

廣告集的狀態 ['未定義' = 0, '草稿' = 1, '已排程' = 2, '運行中' = 3, '已暫停' = 4, '已停止' = 5, '已完成' = 6]

廣告的狀態 ['未定義' = 0, '草稿' = 1, '待審批' = 2, '已批准' = 3, '已審核' = 4]

活動的目標類型 ['未定義' = 0, '宇宙' = 1, '資產' = 2, '沉浸式廣告' = 3]

與廣告相關的創意類型 ['未定義' = 0, '圖像' = 1, '視頻' = 2]

格式的高度（以像素為單位）。

格式的寬度（以像素為單位）。

調用者可以廣告的經驗的標識符，作為十進制字符串。
通過 Open Cloud Universe API 解決其名稱。

要查找的活動 ID。必填。每個請求最多 100 個。

無法解析的 ID。在所有 ID 解析成功時省略。

每個成功解析的活動一個條目。

出價策略。v1 活動始終為 `AUTOMATED`。

帳戶創建的時間，作為 RFC 3339 UTC 時間戳。

帳單帳戶的唯一標識符。作為 {id} 路徑參數使用。

帳戶的當前狀態。可以是 `ACTIVE`、`DISABLED` 或 `ARCHIVED`。

該帳戶的報告日期和預算時間表解釋的 IANA 時區。示例：`America/Los_Angeles`。

帳戶類別。外部廣告商始終為 SELF_SERVICE；MANAGED 和 INTERNAL 為 Roblox 操作的帳戶。可以是 `SELF_SERVICE`、`MANAGED` 或 `INTERNAL`。

帳戶最後更新的時間，作為 RFC 3339 UTC 時間戳。

預算金額（微美元），作為十進制字符串（例如，`5000000` =
$5.00）。錢以字符串方式發送和返回，以便大型值在每個客戶端中保持完整的精度。在請求中，它必須是微美元的數字字符串。

待減少的預算的排隊低預算，以微美元為十進制字符串
（與 amountMicros 相同格式）。預算增加立即生效，但正在運行的活動的減少在帳戶所在時區的下一個午夜應用；到那時該活動保持在 amountMicros 上（當前的較高預算）。待減少待定時省略。

待定預算減少生效的時間，作為 RFC 3339 UTC 時間戳。
待減少待定時省略。

預算步驟。在創建活動時固定。可以是 `DAILY` 或 `LIFETIME`。

活動創建的時間，作為 RFC 3339 UTC 時間戳。

活動廣告的 Open Cloud 圖像資產 ID，作為十進制字符串。

當前服務狀態，由系統推導（唯讀）。可以是 `SERVING`、`IN_REVIEW`、`NOT_SERVING` 或 `REJECTED`。

當前 deliveryStatus 背後的原因，例如為什麼活動不在服務或被拒絕，或在服務中的活動上升期間為 `LEARNING`。當沒有時省略。

服務器分配的活動唯一標識符。

活動的廣告目標。在 v1 中僅支持 `ENGAGEMENT`。

活動的支付方式。在創建活動時固定。可以是
`CREDIT_CARD`、`ADS_CREDIT` 或 `INVOICE`。

您通過更新請求控制的生命週期狀態。可以是 `ACTIVE`、`PAUSED` 或 `CANCELLED`。 `CANCELLED` 是永久的。

活動最後更新的時間，作為 RFC 3339 UTC 時間戳。

為什麼 ID 無法解析。`NOT_FOUND` 意味著該活動不存在或不被調用者擁有。

支持的創意格式及其像素尺寸。

對請求的經驗的資格結果。僅在請求中提供 universeId 時存在。

您可以創建的活動目標。在 v1 中僅支持 `ENGAGEMENT`。

調用者帳戶可用的支付類型。值可以是
`CREDIT_CARD`、`ADS_CREDIT` 或 `INVOICE`。

當前服務狀態。可以是 `SERVING`、`IN_REVIEW`、`NOT_SERVING` 或 `REJECTED`。

當前 deliveryStatus 背後的原因。當沒有時省略。

生命週期狀態。可以是 `ACTIVE`、`PAUSED` 或 `CANCELLED`。

可選出價策略。在 v1 中僅接受 `AUTOMATED`；可以省略。

要廣告的 Open Cloud 圖像資產 ID，作為十進制字符串。必填。
資產必須已經存在並且可以被調用者使用。

廣告目標。必填。在 v1 中僅支持 `ENGAGEMENT`。

活動的支付方式。必填。可以是 `CREDIT_CARD`、`ADS_CREDIT` 或
`INVOICE`，具體取決於帳單帳戶的支持。

可選的受眾定位。省略或發送空對象以覆蓋所有受眾。

支持此創意的 Open Cloud 圖像資產 ID，作為十進制字符串。

資產的媒體類型。在 v1 中僅支持 `IMAGE`。

創意添加到庫中的時間，作為 RFC 3339 UTC 時間戳。

資產的高度（以像素為單位）。當未知時省略。

創意庫條目的標識符。這與 assetId 不同。

該創意是否已被檔案歸檔（軟刪除）。

資產的內容審查結果。可以是 `PENDING_REVIEW`、`APPROVED` 或 `REJECTED`。

資產的生成方式。可以是 `UPLOAD` 或 `IN_HOUSE_GEN_AI`。

該創意所關聯的經驗識別符（如果有），作為十進制字符串。如果不與經驗關聯，則省略。

創意最後更新的時間，作為 RFC 3339 UTC 時間戳。

資產的寬度（以像素為單位）。當未知時省略。

個別錯誤。至少有一個條目；每個條目都有代碼和消息。

HTTP 狀態碼，這裡重複為了方便。

調用者可以廣告的完整經驗集。此端點不進行分頁；整個列表在一次回應中返回。

下一頁的游標。作為 pageToken 傳遞以獲取下一頁。
在最後一頁上缺失。

穩定的、機器可讀的錯誤代碼（例如，`INVALID_ARGUMENT`、
`NOT_FOUND`、`PERMISSION_DENIED` 或 `RATE_LIMITED`）。

活動從開始時間運行的長度，以天為單位。不得超過 3650（大約 10 年）。

在 v1 中不接受，也不會返回；提供它會返回 400。使用
durationInDays 來設置活動結束的時間。保留用於未來的目標。

活動開始服務的時間，作為 RFC 3339 UTC 時間戳。在創建
請求中，必須不在過去。

要投遞的年齡組。空表示所有年齡。值可以是 `AGE_13_17`、
`AGE_18_24` 或 `AGE_25_PLUS`。

要投遞的 ISO 3166-1 alpha-2 國家代碼（例如，`US`）。空表示所有國家。

要投遞的設備類型。空表示所有設備。值可以是 `PHONE`、
`TABLET`、`DESKTOP` 或 `CONSOLE`。

可選的年齡範圍。值可以是 `AGE_13_17`、`AGE_18_24` 或 `AGE_25_PLUS`。

可選的 ISO 3166-1 alpha-2 國家代碼（例如，`US`）。

可選的設備類型。值可以是 `PHONE`、`TABLET`、`DESKTOP` 或 `CONSOLE`。

該經驗不合格的原因。合格時省略。值可以是
`NO_PERMISSION` 或 `BLOCKED`。

新的預算金額（微美元），作為十進制字符串（例如，
`5000000` = $5.00）。錢以字符串發送，因此大型值在每個客戶端中保持完整的精度。必須是微美元的數字字符串。

在 v1 中不變；包括它會返回 400。

預算變更。僅金額是可修改的；預算類型在創建時固定，因此不屬於該對象。發送 `type` 返回 400。

日程變更。僅在活動開始之前允許。

生命週期過渡：`ACTIVE` 以運行或恢復，`PAUSED` 暫停，或 `CANCELLED` 永久取消。

可配置的密鑰，允許對 Roblox 資源進行細粒度訪問。詳細信息請參見 https://create.roblox.com/docs/cloud/auth/api-keys。

x-api-key

表示 Roblox 用戶身份的瀏覽器 Cookie。請勿分享此物。分享此物會允許他人以您的身份登錄，並竊取您的 Robux 和物品。我們不建議使用 Cookie 來調用端點。在可能的情況下，請改用帶有 x-api-key 標頭的 API 密鑰或 OAuth 2.0 進行身份驗證。

.ROBLOSECURITY

構建或授權應用程序以訪問 Roblox 資源。詳細信息請參見 https://create.roblox.com/docs/cloud/auth/oauth2-overview。

Roblox API。詳情請參見 https://create.roblox.com/docs/cloud/open-cloud。

Roblox API

返回帳單帳戶可廣告的每個體驗的宇宙 ID。完整列表將在單個回應中返回；此端點不進行分頁。使用這些 ID 在創建活動時設置 targetUniverseId，並通過 Open Cloud 宇宙 API 獲取體驗名稱。

ad.campaign:read

列出由已驗證的用戶擁有的帳單帳戶。每個帳戶包含其類型、狀態、時區以及創建/更新時間戳。結果以游標（pageToken）進行分頁。

每頁的最大結果（1-100，默認為 50）

maxPageSize

來自先前的 nextPageToken 的不透明游標

pageToken

ad.billing:read

返回由已驗證的用戶擁有的單個帳單帳戶。如果帳戶不存在或不屬於呼叫者，則返回 404。

返回創建活動時接受的值：支持的目標、支付類型、廣告格式和定位維度。提供 universeId 時，回應還包括一個合格塊，指示該體驗當前是否可以被廣告，以及當無法廣告時的原因。

universeId

目標過濾器（在 v1 中為 ENGAGEMENT）

objective

列出呼叫者帳單帳戶中的活動。活動按狀態分組（先活動，然後暫停，然後取消），並在每組內按最新的時間排序。結果通過游標（pageToken）進行分頁；每個頁面返回最多 maxPageSize 的活動（默認 50，最大 100）。

每頁的最大結果（1-100，默認 50）

在帳單帳戶中創建廣告活動。您引用的創意必須已存在為您擁有使用權限的 Open Cloud 圖像資產；當活動創建時，這些資產經過驗證並保存到您帳戶的可重用創意中。成功時，返回的活動的 deliveryStatus 為 IN_REVIEW，表示它正在排隊進行廣告政策審核，尚未開始服務 — 請輪詢該活動（或 campaigns:batchGetStatus），直到這一情況改變。budget.amountMicros 是以十進制字符串表示的微美元預算（例如 "5000000" = 5.00 美元）。必須至少達到最低活動預算；小於最低值的金額將返回 400，並在錯誤消息中說明所需的最低值。schedule.durationInDays 不能超過 3650（約 10 年）。必須提供 x-idempotency-key 標頭，且必須是 UUID：在 24 小時內重試相同的標識鍵及其相同的主體將返回原始活動（200），而重用不同主體的標識鍵將返回 409。

冪等性鍵（UUID）；24小時去重窗口。相同重放將返回原始活動（200）；不匹配的重放可能會衝突（409）。

x-idempotency-key

活動已創建，或是對先前使用相同鍵和主體的創建的冪等重放

驗證錯誤、無效的資產或傳送了 endTime

無法管理帳戶、宇宙不可廣告或 USE 權限被拒絕

冪等性鍵與不同的請求主體重複使用，或並發寫入衝突

ad.campaign:write

返回單個活動，包括其狀態（您控制的生命週期狀態：ACTIVE、PAUSED 或 CANCELLED）及其 deliveryStatus（無論它是否正在服務：SERVING、IN_REVIEW、NOT_SERVING 或 REJECTED）。deliveryStatusReasons 列出了任何影響交付的原因 — 例如為何活動未在服務或被拒絕，或一個正在服務的活動仍在其初始學習階段。如果活動不存在或不屬於呼叫者，則返回 404。

更新活動的可變字段。您可以更改：name、budget.amountMicros、schedule.startTime 和 schedule.durationInDays（僅在活動開始之前允許更改日程安排）以及狀態。將狀態設置為 ACTIVE 以運行或恢復活動，設置為 PAUSED 以暫停活動，或設置為 CANCELLED 以永久取消。budget.type 不能更改 — 僅能更改金額。預算增加立即生效，但在正在進行的活動上降低預算將排定至帳戶時區的下個午夜；在降低預算待定期間，回應在 budget.scheduledAmountMicros 和 budget.scheduledEffectiveTime 中報告。目標、支付類型、定位、creativeAssetIds 和出價字段在創建後是固定的，如果包含將返回 400。返回更新的活動，並重新計算其 deliveryStatus。

返回頂多 100 個活動的狀態（生命週期狀態）和 deliveryStatus（活動當前是否正在服務），以及 deliveryStatusReasons。這是建議一次輪詢多個活動的審核和服務狀態的方式。提供活動 ID 在 campaignIds；任何未找到或不屬於呼叫者的 ID 將在 failures 數組中返回，理由為 NOT_FOUND。

列出保存到呼叫者帳單帳戶中的可重用創意。每個創意包括其 assetId、名稱、審核狀態、尺寸及來源。使用 isArchived 按存檔狀態過濾。結果以游標（pageToken）進行分頁。

isArchived

campaignTargetType

campaignTargetId

指示是否在響應中包含報告統計

includeReportingStats

要檢索的頁面的游標。如果為空，則獲取第一頁

pageCursor

22: 無效的活動目標 ID。
23: 無效的活動目標類型。

根據指定的輸入參數獲取 Roblox.AdConfiguration.Api.SponsoredCampaignModel 的一頁。

Roblox.AdConfiguration.Api.Models.CreateSponsoredCampaignRequest

2: 每日預算低於最低允許的數額。
3: 總預算必須大於 0。
4: 廣告名稱不能為空。
5: 開始日期不能是未來的日期。
6: 結束日期必須是未來的日期。
7: 開始日期必須早於結束日期。
8: 總預算不符合每日支出和排定的天數
9: 無法為指定的宇宙 ID 加載宇宙。
11: 無效的目標年齡範圍。
12: 無效的目標性別。
13: 無效的目標設備類型。
14: 無效的廣告集 ID。
15: 廣告名稱不能超過 255 個字符。
16: Robux 餘額不足。
17: 名稱已被佔用。
18: 每日預算超過允許的最大值。
19: 無效的組 ID。
20: 排定的天數超過最大允許天數。
21: 您的體驗目前不符合廣告資格。
22: 無效的活動目標 ID。
23: 無效的活動目標類型。
24: 無效的創意 ID。
25: 無效的創意類型。
28: 總預算必須是活動持續時間 * 每日競標
29: 目標不符合新計劃的資格
30: 無效的用戶 ID

0: 此請求的授權已被拒絕。
10: 權限不足。

0: 發生未知錯誤。
31: 內部伺服器錯誤

創建一個完整的廣告。包括廣告活動、廣告組、保證金和廣告。
當前僅用於創建贊助。

獲取所有有資格贊助的資產類型 ID。

Roblox.AdConfiguration.Api.Models.GetEligibleCampaignTargetsRequest

0: 令牌驗證失敗
10: 權限不足。

返回用戶授權贊助的 Roblox.AdConfiguration.Api.Models.CampaignTargetModel 集合，按最近廣告排序

Ads.Management.Service.CampaignTargetType.

campaignTargetIds

檢查目標是否有資格獲得贊助，並
檢查用戶是否獲准贊助這些目標。

Roblox.AdConfiguration.Api.Models.StopSponsoredCampaignRequest

10: 權限不足。
14: 無效的廣告集 ID。
31: 內部伺服器錯誤

停止由用戶發起的贊助活動 / 廣告（廣告集）運行。

Advertising

体验

虚拟形象

素材

范例和项目

引擎 API

Open Cloud API

Studio

分析

平台

教程

创作者计划

教育

课程

学习

此方法是异步的，会返回一个`Operation`对象，该对象表示操作的当前状态。它包含一个端点路径，您可以轮询该路径以获取实际响应和相关的元数据。有关长时间运行操作的更多信息，请参阅[文档]({longRunningOperationsLink})。

以下部分描述了操作完成时提供的响应和元数据对象。

Beta 测试终点已准备好公开使用。可能出现导致功能无法正常运作的更改，但几率极低。

这些 Open Cloud 文档页面将于 2026 年 3 月 31 日移除。届时你将被自动重定向到新的 Open Cloud 文档。{linkStart}了解更多{linkEnd}

这些旧 Open Cloud 页面将于 2026 年 3 月 31 日移除并重定向。{linkStart}了解更多{linkEnd}

实验性终端节点已准备好供公众使用，但随着 API 协定的最终确定，可能偶尔会出现重大变更。

此终端节点可通过使用 API 密钥的 {httpServiceLinkStart}HttpService{httpServiceLinkEnd} 在体验中调用。

此字段可能在创建资源时被设置，但可能无法在后续请求中修改。

这些字段可能在创建资源时被设置，但可能无法在后续请求中修改。

此字段可以在请求中提供，但永远不会包括在答复中。

旧版验证方法。始终首选使用 API 密钥或 OAuth 2.0（如有）。

每个 API 密钥：每个 IP 地址每 {periodInSeconds} 秒有 {maxInPeriod} 次请求

无需身份验证即可调用。通常会显著降低速率限制。始终首选使用 API 密钥或 OAuth 2.0（如有）。

对于每个分组，只需提供架构中的以下字段之一，其余字段可以排除。

你可以随时重新选择加入。{linkStart}提供反馈。{linkEnd}

你正在查看旧版文档。{linkStart}提供反馈。{linkEnd}

你可以随时退出，并重定向回旧的引用页面。{linkStart}在这里提供反馈。{linkEnd}

你正在查看全新改版的文档。{linkStart}提供反馈。{linkEnd}

此字段可能被设置为响应，但在请求中将被忽略。

注意：在高流量期间，速率限制可能会更低。某些终端节点有额外的速率限制。[进一步了解速率限制]({link})。

用户或群组所有 API 密钥每天 {limit} 个请求

用户或群组所有 API 密钥每小时 {limit} 个请求

用户或群组所有 API 密钥每分钟 {limit} 个请求

用户或群组所有 API 密钥每秒 {limit} 个请求

每个 API 密钥所有者每分钟 {limit} 个请求

每个 App 用户每天 {limit} 个请求

每个 App 用户每小时 {limit} 个请求

每个 App 用户每分钟 {limit} 个请求

每个 App 用户每秒 {limit} 个请求

每个 API 密钥所有者每秒 {limit} 个请求

范围可以控制你的凭据拥有哪些权限。你的凭据只能访问你所选范围支持的终端节点。

稳定终端节点已准备好投入生产使用，在其生命周期内几乎不会发生重大变更。

此目标允许你将密钥的访问权限限制为选定的{requiredParts}

此目标允许你将密钥的访问权限限制为选定的{requiredParts}和{optionalParts}

目标类型用于限制你的凭据可操作的资源。即使你的帐户拥有其他资源的权限，也只能处理选定的资源。某些范围没有目标部件，在这种情况下，你的所有相关资源都可进行操作。

对于用户拥有的 API 密钥，无需选择宇宙顶级部件。在这种情况下，你的 API 密钥可以访问你拥有的所有个人体验，以及你在群组中拥有相应权限的群组体验。

尚不支持试用需要 API 密钥或 OAuth 2.0 验证的终端节点

为了安全起见，已停用高风险操作的 Cookie 验证。

关键风险终端节点非常敏感，为了安全起见，已停用“试用”

注意：此代码示例中不包含验证标头。你可能需要添加验证标头，以便此命令能够正常运作。

这是会修改或删除关键数据的高风险终端节点。测试时要格外小心。

此 API 终端节点已被归类为高风险，可能会影响实时数据或用户帐户。

对高风险 API 的已验证请求可能会进行无法撤销的更改。请在继续之前仔细查看你的请求参数。

这是会取回数据的低风险终端节点。通常可以安全测试。

这是会修改数据的中风险终端节点。请使用非关键帐户仔细测试，因为更改可能是永久性的。

为了确保你帐户的安全，请不要在此处粘贴来自其他来源的文本，或将此页面的信息发送给其他人。

你即将使用实际帐户凭据测试实时 API 终端节点。

只有在你了解即将进行的 API 调用的影响后才能继续。在测试之前，请仔细查看 API 文档。

将使用已验证的会话进行 API 调用

这些是可能影响你帐户或数据的真实 API 调用

某些操作可能会修改或删除数据

此终端节点已被以下推荐的替代终端节点取代：

调用此终端节点需要以下范围。如需
有关生成正确密钥的更多信息，请参阅 [管理 API 密钥]({apiKeyReferenceDocLink})。

如需有关生成密钥的更多信息，请参阅 [管理 API 密钥]({apiKeyReferenceDocLink})。

相对于基础 URL 的路径，下列端点是可用的。

此字符串格式为 [FieldMask](/cloud/reference/types#fieldmask)。

JSON 值可以是 “null”、“boolean”、“string”、“number”、“array” 或 “object”。

你的 OAuth 2.0 应用程序需要以下范围才能使用此终端节点。如需进一步了解如何注册 OAuth 2.0 应用程序，请参阅 [App 注册和审核]({oauth2ReferenceDocLink})。

如需进一步了解如何注册 OAuth 2.0 应用程序，请参阅 [App 注册和审核]({oauth2ReferenceDocLink})。

下列对象描述了接受或返回的有效载荷。请参阅每个单独的端点，以了解更多关于这些对象用途的信息。

调用此终端节点需要以下范围。

资源路径

若要使用此端点，你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息，请查看【应用程序注册及评价】({oauth2ReferenceDocLink})。