概览
- POST accounts/:account_id/cards Tweets：
- POST accounts/:account_id/tweets - 要将卡片添加到 Tweets，请使用 card_uri 参数。 计划 Tweets：
- POST accounts/:account_id/scheduled_tweets
Cards
图片
- 网站：1:1 和 1.91:1
- 图片应用下载：1:1 和 1.91:1
- 图片会话：1.91:1
- 图片私信：1.91:1
- 投票：1.91:1
视频
- 视频网站：16:9 和 1:1
- 视频应用下载：16:9 和 1:1
- 投票：16:9
- 视频会话：16:9
- 视频私信：16:9
推广视频
media_id 通过 POST accounts/:account_id/videos 端点将该视频与广告账户关联。视频的 id（有时称为 media_key）将用于后续请求。该值是一个以整数开头、后接下划线、并以较长数值结尾的字符串，例如：13_875943225764098048。
推广视频（Tweet 内）
id。在此步骤中，你还可以提供视频标题、描述和号召性用语（CTA）。这些信息将对用户可见。
卡片中的推广视频
- POST accounts/:account_id/cards/video_website
- POST accounts/:account_id/cards/video_app_download
- POST accounts/:account_id/cards/video_conversation
id，以及可选的图片 media_id（作为封面图）。
最后，使用 POST accounts/:account_id/tweet 端点创建 Tweet。通过 card_uri 参数将卡片附加到 Tweet。
常规信息
- （截至 2015-10-22）上传用于推广内容的视频时，发送至 POST media/upload (chunked) 端点的所有
INIT命令请求，必须将media_category参数设为amplify_video。使用此新参数可确保视频以异步方式预处理，并为用于推广内容做好准备。视频上传后，可使用STATUS命令检查异步处理是否完成。 - 目前允许的推广视频最长为 10 分钟，文件大小不超过 500MB。
- 上传视频应为 mp4 或 mov 格式。
- 上传视频通常处理较快，但处理时间可能因视频长度和文件大小而异。
- 上传的封面图应为 png 或 jpg 格式。宽高比和尺寸不作要求，但封面图会调整以适配视频播放器。
使用指南
计划发布的 Tweet
介绍
- 创建、修改并查看新近安排的 Tweet
- 将 Scheduled Tweet 与 line item 关联
- 查询并管理现有的已安排 Tweet
- Scheduled Tweet 上线后，检索对应的上线 Tweet 的
id
API 端点
预定 Tweet 管理
- GET accounts/:account_id/scheduled_tweets（获取所有预定 Tweet 的列表）
- GET accounts/:account_id/scheduled_tweets/:scheduled_tweet_id（使用其
id查询特定的预定 Tweet） - POST accounts/:account_id/scheduled_tweets（创建新的预定 Tweet）
- PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id（修改现有的预定 Tweet）
- DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id（使用其
id删除预定 Tweet） - GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id（预览现有的预定 Tweet）
预定投放的推广 Tweet
- GET accounts/:account_id/scheduled_promoted_tweets（检索所有预定投放的推广 Tweet 列表）
- GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id（根据其
id查询某条预定投放的推广 Tweet） - POST accounts/:account_id/scheduled_promoted_tweets（创建新的预定投放的推广 Tweet）
- DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id（根据其
id删除现有的预定投放的推广 Tweet）
预定 Tweet 视图
计划创建 Scheduled Tweet：
- 验证已认证用户是否有权限为指定 @handle 创建自然（非付费）Tweets。创建“仅推广”Tweet 的权限要求已认证用户为该账户用户，并具有 Tweet composer permissions。
- 验证在 scheduled_at 指定时间前后 15 分钟的窗口内，计划创建的 Tweets 不超过 30 条。出现 SCHEDULED_TWEET_LIMIT_EXCEEDED 错误表示在同一未来 15 分钟时间段内安排了过多的计划 Tweet。广告主需要删除现有的计划 Tweet，或将 scheduled_at 时间适当前移或后移。
预定的 Tweet 进入“发布”状态：
- 这些验证规则会在 scheduled_at 指定的时间运行，与在 API 中创建常规 Tweet 时适用的规则相同。例如，如果预定的 Tweet 同时包含图片和 GIF，则它不会发布，scheduled_status 将被设置为 FAILED
工作流程
scheduled_at 时间；如果 Tweet 未包含任何媒体实体，还需提供 Tweet 的 text。此外，该端点还提供一些可选项，允许你通过 as_user_id 参数代表其他 @handle 创建 Scheduled Tweet，并可添加卡片（card_uri）以及媒体（media_ids）。注意，单个 Tweet 只能包含同一类型的实体，即视频、GIF 或图片中的一种。nullcast 参数用于控制该 Tweet 是否为“仅推广”Tweet。所有新创建的 Scheduled Tweet 默认都是“仅推广”（nullcast=true）。如果 nullcast=false，则会创建自然 Scheduled Tweet。
成功创建 Scheduled Tweet 后，响应会包含一个 id 字段，表示该 Scheduled Tweet 本身的唯一标识符。除此之外，还会返回一个名为 tweet_id 的字段。该字段最初为 null，但当 Tweet 发布后，该字段将填入该“已发布”Tweet 的 ID。
tweet_id 字段将被填入该“live”Tweet 的 ID。
查看 Scheduled Tweet
随后可使用 GET accounts/:account_id/tweet_previews 端点，结合上一步中的 Scheduled Tweet id 生成该 Tweet 的预览。API 响应将包含一个 iframe URL，可直接用于渲染该 Scheduled Tweet 的预览。相关 CSS 和图像将由 X 直接提供。
nullcast=true）的 Tweet，这两种类型的任意一种都可以与一个 line item 关联。为此，我们还提供了一个 POST accounts/:account_id/scheduled_promoted_tweets 端点。该端点仅允许在一次 API 调用中将单个“预定推广”Tweet 关联到一个 line item。若需将多个预定 Tweets 关联到同一个 line item，需要进行多次 API 调用。
请注意，无法修改现有的预定推广 Tweet。
SCHEDULED 状态，以及该预定 Tweet 是否符合所设定的投放目标，但不会执行其他验证。适用于线项和预定 Tweet 的其余验证规则会在该 Tweet 实际“上线”时执行。
为确保广告系列正常投放，建议将预定 Tweet 的 scheduled_at 时间设置在广告系列/线项投放期开始之前。
例如，若预定 Tweet 设定在广告系列开始日期之后上线（且仅有一个 Tweet 与一个线项关联），则广告系列的状态将为 ACTIVE，但由于预定 Tweet 尚未上线，将没有可用于投放的创意。
预定 Tweet 管理
其余一组端点允许 API 使用方管理其所有预定 Tweet 和预定推广 Tweet。这些 API 可用于返回所有预定 Tweet 的列表（可按给定状态进行可选筛选），以及通过其 id 查询指定的预定 Tweet。
预定的 Tweet 上线时会发生什么？
scheduled_at 时间）时，将进行以下更新：
- 会创建“已上线”的 Tweet，但可能会有最长 1 秒的延迟
- 会将
tweet_id添加到以下实体： - 预定的 Tweet
- 推广的预定 Tweet
- 会创建一个新的推广 Tweet 实体
最佳实践
- 在创建计划发布的 Tweet 时，确保该 Tweet 合规有效（例如，Tweet 只能包含图片、视频或 GIF 三者之一，不能组合使用）
- 确保广告投放周期（即
start_time和end_time）与该计划发布 Tweet 的scheduled_at时间一致 - 计划发布的 Tweet 的发布时间不应设置为距离当前超过一年（365 天）
- 目前计划发布的 Tweet 不支持预览（即在创建前预览计划发布的 Tweet 的功能）
媒资库
简介
Media Library 端点用于管理 X Ads 账户中的图片、GIF 和视频。库中的媒体资产可用于 Tweet 和创建卡片，也可在多个创意中复用，从而无需反复上传同一资产。API 端点
- POST media/upload 或 POST media/upload（分段）（上传媒体）
- POST accounts/:account_id/media_library（将媒体添加到媒体库）
添加到库
请求参数
属性
用法
识别卡片类型
介绍
| card_uri | preview_url |
|---|---|
| card://1043282691834048513 | https://cards.x.com/cards/18ce54d4x5t/68w3s |
使用 card_uri 识别 Tweet
对于使用卡片 URI 值创建的 Tweet，请在 card_uri 响应属性中查找对该卡片的引用。下面的示例响应使用 GET accounts/:account_id/tweets 端点。使用 preview_url 识别 Tweet
对于在 Tweet 文本中包含预览 URL 创建的 Tweet，可在 entities[“urls”][i][“expanded_url”] 中找到该 URL（text 字段包含缩短的 t.co URL），其中 i 为数组索引（一个 Tweet 可以包含多个 URL）。 对于已安排发布和草稿的 Tweet 对象，预览 URL 将始终出现在 text 字段中。获取卡片
媒体识别
简介
可以将媒体（图片、GIF 和视频）添加到 Tweet 和卡片中。此外，视频可用作前贴片素材，图片可在 X Audience Platform 上进行推广。本节说明如何在这些实体中定位媒体引用。 媒体标识符有两种类型：ID 和 key。下面给出了每种类型的示例值。| 媒体 ID | 媒体 key |
|---|---|
| 1029825579531807971 | 13_1029825579531807971 |
图像
| 资源 | 标识符 | 属性 |
|---|---|---|
| Image cards | 无 | |
| Tweet | 两者皆有 | entities["media"]["id_str"] entities["media"]["media_key"] |
| Scheduled Tweet | 两者皆有 | media_ids and media_keys |
| Draft Tweet | 两者皆有 | media_ids and media_keys |
| Account Media | 无 | |
| Media Library | 两者皆有 | media_id and media_key |
| 资源 | 属性 | 格式 |
|---|---|---|
| Image cards | image | .jpg |
| Tweet* | entities["media"][0]["media_url"] or extended_entities["media"][i]["media_url"] | .jpg |
| Scheduled Tweet | 无 | |
| Draft Tweet | 无 | |
| Account Media | media_url | .jpg |
| Media Library | media_url | .jpg |
- 此 URL 的位置取决于 Tweet 是否包含单张或多张图片。
视频
| 资源 | 标识符 | 属性 |
|---|---|---|
| 视频卡片 | 可能为任一类型 | video_content_id |
| 含投票的视频卡片 | 无 | |
| Tweet | 两者皆有 | entities["media"]["id_str"] entities["media"]["media_key"] |
| 预定的 Tweet | 两者皆有 | media_ids 和 media_keys |
| 草稿 Tweet | 两者皆有 | media_ids 和 media_keys |
| 账户媒体 | Media key | video_id |
| 媒体库 | 两者皆有 | media_id 和 media_key |
| 资源 | 属性 | 格式 |
|---|---|---|
| 视频卡片 | video_url 和 video_hls_url | .vmap .m3u8 |
| 含视频的 Tweet | extended_entities["media"][i]["video_info"]["variants"][j]["url"] | .mp4 |
| 预定的 Tweet | 无 | |
| 草稿 Tweet | 无 | |
| 账户媒体 | 无 | |
| 媒体库 | media_url | .mp4 |
video_url 和 video_hls_url 响应属性，分别提供 .vmap 和 .m3u8 的 URL。
媒体库
| 资源 | 是否在媒体库中 |
|---|---|
| 图片卡片 | 否 |
| 视频卡片 | 是* |
| Tweets（任意媒体）** | 是 |
| 计划发送的 Tweets | 是 |
| 草稿 Tweets | 是 |
| Account Media 图片 | 否 |
Account Media 视频（PREROLL） | 是 |
- 适用于其
video_content_id为 media key 的卡片。若该值为 media ID，资产仍存在于媒体库中，但检索时需要在其前添加数字前缀和下划线。 ** Tweets 仅返回 media ID。虽然资产保证存在于媒体库中，但获取时需要在其前添加数字前缀和下划线。
- 当 AMPLIFY_VIDEO 资产添加到媒体库时，会作为 PREROLL 创意类型自动添加为 Account Media 资产。
- 当具有特定尺寸的图片（参见我们枚举页面中的“Creative Types”）被添加到媒体库时，会自动添加为 Account Media 资产。创意类型（如 INTERSTITIAL）取决于图片尺寸。
Tweets
简介
X Ads API 支持三种类型的 Tweet：已发布、已排程和草稿。Nullcasted 推文
推广 Tweet
Tweet ID
轮播
介绍
- 上传媒体
- 创建卡片
- 创建 Tweet
- 推广 Tweet
端点
JSON POST 正文
- 一个
SWIPEABLE_MEDIA组件，接受一个媒体键数组 - 以下二选一：
- 一个
DETAILS组件，用于指定网站信息 - 一个
BUTTON组件，用于指定应用信息
SWIPEABLE_MEDIA 组件必须包含一个 media_keys 数组，可在其中指定 2 到 6 张图片或视频。传入媒体键的顺序将决定它们的渲染顺序。
| 网站 | 应用 | |
|---|---|---|
| 指定组件类型 | "type": "DETAILS" | "type": "BUTTON" |
| 标题/标签 | "title": "X" | "label": { "type": "ENUM", "value": "INSTALL" } |
| 目标 | "destination": { "type": "WEBSITE", "url": "https://www.x.com" } | "destination": { "type": "APP", ... } |
BUTTON 组件中的应用（App）目标对象需要提供国家/地区代码以及至少一个应用标识符；还可以选填深度链接。有关这些字段的说明，请参阅参考文档。
综合以上要求，下面给出一个应用轮播的 JSON POST 请求体示例。
示例
media_type 请求参数将结果限定为特定媒体类型。
card_uri，创建 Tweet 时将会用到该值。
Tweet
使用 POST accounts/:account_id/tweet 端点创建你的 Tweet，并使用上一个请求返回的 card_uri。（为便于阅读，响应已截断。）
创意元数据标注
介绍
标记创意素材
exiftool -contributor="<YOUR APP ID>" -creative_file.jpg
exiftool -date="<date>" -creative_file.jpg
应用 id 可在开发者门户的 Projects & Apps 下找到。示例：16489123
以下示例为一张图片添加应用 id 作为 contributor 标签，以及 date 作为 date 标签：
exiftool -xmp:all -G1 <filename>
示例：
exiftool -xmp:all -G1 eiffel_tower.jpg
有疑问？
API 参考文档
账号媒体
GET accounts/:account_id/account_media
获取与当前账户关联的部分或全部账户媒体的详细信息。资源网址
https://ads-api.x.com/12/accounts/:account_id/account_media
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| account_media_ids 可选 | 通过指定以逗号分隔的标识符列表，仅返回所需的账户媒体。最多可提供 200 个 ID。 类型：string 示例：3wpx |
| count 可选 | 指定每个请求尝试检索的记录数。 类型：int 默认值：200 最小值/最大值：1/1000 |
| creative_types 可选 | 仅返回匹配指定创意类型的账户媒体。可通过逗号分隔的枚举值指定多个创意类型。 类型：enum 可能的取值：BANNER、BANNER_TABLET、INTERSTITIAL、INTERSTITIAL_LANDSCAPE、INTERSTITIAL_LANDSCAPE_TABLET、INTERSTITIAL_TABLET、MEDIUM_RECTANGLE、PREROLL、VAST_PREROLL |
| cursor 可选 | 指定用于获取下一页结果的游标。详见 Pagination。 类型：string 示例：8x7v00oow |
| sort_by 可选 | 按受支持的属性进行升序或降序排序。详见 Sorting。 类型：string 示例：created_at-asc |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true、false |
| with_total_count 可选 | 包含 total_count 响应属性。 注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将有较低的速率限制，目前为每 15 分钟 200 次。 类型：boolean 默认值：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media?account_media_ids=3wpx
示例响应
资源网址
https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 该杠杆账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| account_media_id 必填 | 本次请求中所操作的账户媒体的引用。 类型：string 示例：2pnfd |
| with_deleted 可选 | 在响应中包含已删除的结果。 类型：boolean 默认：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd
示例响应
资源网址
https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账号的标识符。该参数出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账号必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| account_media_id 必填 | 本次请求中所操作的账号媒体资源引用。 类型：string 示例：2pnfd |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd
示例响应
卡片
注意：要将卡片与 Tweet 关联，请在以下任一端点中使用card_uri 参数：POST accounts/:account_id/tweet、POST statuses/update、POST accounts/:account_id/scheduled_tweets 或 POST accounts/:account_id/draft_tweets。
获取与当前账户关联的部分或全部卡片的详细信息。
注意：仅返回通过 POST accounts/:account_id/cards 端点创建的卡片。通过其他端点创建的卡片不会返回。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 所使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型: string 示例: 18ce54d4x5t |
| card_types 可选 | 通过指定以逗号分隔的枚举值列表，将响应限定为所需的卡片类型。 类型: enum 可能的取值: IMAGE_APP, IMAGE_CAROUSEL_APP, IMAGE_CAROUSEL_WEBSITE, IMAGE_MULTI_DEST_CAROUSEL_WEBSITE, IMAGE_WEBSITE, MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE, VIDEO_APP, VIDEO_CAROUSEL_APP, VIDEO_CAROUSEL_WEBSITE, VIDEO_MULTI_DEST_CAROUSEL_WEBSITE, VIDEO_WEBSITE |
| card_id 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的卡片。最多可提供 200 个卡片 ID。 类型: string 示例: 1044294149527166979,1044301099031658496 |
| card_uris 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的卡片。最多可提供 200 个卡片 URI 值。 类型: string 示例: card://1044294149527166979,card://1044301099031658496 |
| count 可选 | 指定每次请求尝试检索的记录数。 类型: int 默认值: 100 最小/最大值: 1、200 |
| cursor 可选 | 指定用于获取下一页结果的游标。更多信息参见 分页。 类型: string 示例: 8x7v00oow |
| include_legacy_cards 可选 | 在响应中包含旧版网站卡和应用卡。旧版卡片是指其资源 URL 符合以下格式：accounts/:account_id/cards/:card_type。更多背景信息参见此开发者论坛帖子。 类型: boolean 默认值: false 可能的取值: true, false |
| q 可选 | 可选查询，用于按 name 限定卡片。省略此参数以检索全部。最大长度：80 个字符。注意：执行不区分大小写的前缀匹配。 类型: string 示例: dtc |
| sort_by 可选 | 按支持的属性进行升序或降序排序。更多信息参见排序。 类型: string 示例: created_at-asc |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型: boolean 默认值: false 可能的取值: true, false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1
示例响应示例
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/:card_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 杠杆账户的标识符。该参数出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| card_id 必填 | 卡片的 id。 类型：string 示例：1044294149527166979 |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true，false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264
示例响应
POST accounts/:account_id/cards
创建与指定账户关联的新卡片。 卡片创建请求只接受 JSON 格式的 POST 请求体。Content-Type 必须设置为 application/json。
有关详细用法示例，请参阅我们的轮播指南。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards
参数
name 和一个 components 数组。组件以对象形式表示，用于描述面向广告主的卡片属性。
下面的示例展示了有效负载的一般结构（但包含不可用的信息）。
| Name | Description |
|---|---|
| account_id required | 被利用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| name required | 卡片名称。最大长度：80 个字符。 类型：string 示例：component based card |
| components sometimes required | 用于创建卡片的组件说明。详见下文。不能与 slides 同时指定。 注意：组件的顺序很重要。 类型：array of objects |
| slides sometimes required | 使用此二维数组创建 Multi-Destination Carousel。将每张卡片描述为组件的分组。每个幻灯片都应完整呈现一张卡片。不能与 components 同时指定。 注意：每个幻灯片的顺序很重要。 类型：array of array |
组件
type 字段，用于确定对象的模式（schema）。Ads API 支持以下组件类型，分为媒体类组件和描述类组件。
- 媒体：
MEDIA：单个视频或图片SWIPEABLE_MEDIA：2 至 6 个视频或图片- 描述：
DETAILSBUTTON
type 键之外）。如下表所示。
组件 type | 字段 | 值类型 |
|---|---|---|
MEDIA | media_key | string |
SWIPEABLE_MEDIA | media_keys | array of strings |
DETAILS | title destination | string object |
BUTTON | label destination | object object |
components 数组中的一个 BUTTON 组件示例（有意省略 name 键）。（省略号表示还需提供更多信息的地方。）
DETAILS 或 BUTTON 组件创建。描述类组件渲染在媒体下方，并带有目标链接，既可以是 URL，也可以是移动应用。
标签
标签定义按钮上显示的文本，因此仅适用于 BUTTON 组件。标签对象有两个必填键：type 和 value。type 必须设置为 ENUM，value 可以是以下之一：BOOK、CONNECT、INSTALL、OPEN、ORDER、PLAY 或 SHOP。
在前述示例基础上，下面展示了 BUTTON 组件中的 label 对象。
DETAILS 或 BUTTON 组件中始终为必填项。目标页面类型有两种：WEBSITE 或 APP。
注意：网站目标仅可与 DETAILS 组件搭配使用，应用目标仅可与 BUTTON 组件搭配使用。
网站目标
| Name | Description |
|---|---|
| type required | 目标类型，用于确定其模式。 类型：enum 可能的取值：WEBSITE |
| url required | 将用户重定向至的网站 URL。 类型：string 示例：https://devcommunity.x.com/c/advertiser-api |
| Name | Description |
|---|---|
| type required | 目标类型，用于确定其模式。 类型：enum 可能的取值：APP |
| country_code required | 应用销售所在国家/地区的 ISO 3166-1 alpha-2 双字母代码。 类型：string 示例：US |
| googleplay_app_id sometimes required | Google Play 应用包名。 注意：以下字段至少需提供一项：ios_app_store_identifier 或 googleplay_app_id。 类型：string 示例：com.twitter.android |
| ios_app_store_identifier sometimes required | iOS App Store 标识符。 注意：以下字段至少需提供一项：ios_app_store_identifier 或 googleplay_app_id。 类型：string 示例：333903271 |
| googleplay_deep_link optional | 通往所推广 Android 应用的深度链接。 注意：仅在已提供 googleplay_app_id 时可用。 类型：string |
| ios_deep_link optional | 通往所推广 iOS 应用的深度链接。 注意：仅在已提供 ios_app_store_identifier 时可用。 类型：string |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards
示例回复
Content-Type 必须设置为 application/json。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264
参数
| Name | Description |
|---|---|
| account_id 必填 | 目标（被使用）账户的标识符。出现在资源路径中，通常是除 GET accounts 以外所有 Advertiser API 请求的必需参数。指定的账户必须与已验证用户关联。 类型：string 示例：18ce54d4x5t |
| name 可选 | 卡片名称。最大长度：80 个字符。 类型：string 示例：component based card |
| components 可选 | 用于更新卡片的组件说明，详见下文。不可与 slides 同时指定。注意：组件的顺序很重要。类型：array of objects |
| slides 可选 | 使用此二维数组更新 Multi-Destination Carousels。将每张卡片描述为组件的分组。每个幻灯片应完整表示一张卡片。不可与 components 同时指定。注意：每个幻灯片的顺序很重要。类型：array of array |
示例请求
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264
示例响应
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/:card_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 使用中的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| card_id 必填 | 要删除的卡片的 id。 类型：string 示例：1044294149527166979 |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264
示例回复
获取卡片
card_uri，检索多个卡片。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/all
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 相关账户的标识符。该值出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| card_uris 必填 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的卡片。最多可提供 200 个卡片 URI 值。 类型：string 示例：card://1044294149527166979,card://1044301099031658496 |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496
示例响应
card_id 获取与当前账户关联的指定卡片。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| card_id 必填 | 你在请求中所操作的卡片的引用。 类型：string 示例：508pf |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf
示例示例
Tweet 草稿
GET accounts/:account_id/draft_tweets
获取与当前账户关联的部分或全部草稿 Tweet 的详细信息。资源 URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| count 可选 | 指定每个请求尝试检索的记录数。 类型：int 默认值：100 最小值、最大值：1、200 |
| cursor 可选 | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 类型：string 示例：c-jh1g0ryb |
| user_id 可选 | 指定要检索草稿 Tweet 的用户。未设置时，默认为该账户上的 FULL 可投放用户。 类型：string 示例：756201191646691328 |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 投放账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已通过身份验证的用户关联。类型：string 示例：18ce54d4x5t |
| draft_tweet_id 必填 | 本次请求所操作的 Draft Tweet 的引用。类型：string 示例：994788364334325760 |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760
示例响应
POST accounts/:account_id/draft_tweets
为该账户的完整可推广用户（默认）或通过as_user_id 参数指定的用户创建一条 Tweet 草稿。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 已授权账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| as_user_id 必填 | 代表其发布 Tweet 的广告主的用户 ID。广告主必须通过 ads.x.com 向你的账号（或多个账号）授予其广告账户的访问权限。该权限允许你使用自己账号的 OAuth 令牌而非广告主的令牌调用 API。 类型：string 示例：756201191646691328 |
| text 有时必填 | 状态更新的文本。如果未指定 media_keys，则为必填。 类型：string 示例：Just setting up my X. |
| card_uri 可选 | 使用任一卡片响应中的 card_uri 值（如果可用）将卡片与 Tweet 关联。 类型：string 示例：card://960880280705392541 |
| media_keys 可选 | 通过指定以逗号分隔的标识符列表，将媒体与 Tweet 关联。最多可包含 4 张图片、1 个动画 GIF 或 1 个视频。 注意：媒体资产必须位于该账户的 Media Library 中。 类型：string 示例：13_1153584529292270722 |
| nullcast 可选 | 是否创建 nullcast（或“仅推广”）Tweet。 类型：boolean 默认值：true 可能的取值：true、false |
| name 可选 | 草稿 Tweet 的名称。最大长度：80 个字符。 类型：string 示例：Tweet with name |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已验证用户关联。 类型：string 示例：18ce54d4x5t |
| draft_tweet_id 必填 | 你在请求中操作的 Draft Tweet 的引用。 类型：string 示例：994747471329873920 |
| card_uri 可选 | 使用任一卡片响应中的 card_uri 值（如果可用）为该 Tweet 关联卡片。 注：通过仅提供参数但不赋值来取消设置（移除）。 类型：string 示例：card://970582057284129151 |
| media_keys 可选 | 通过指定以逗号分隔的标识符列表，为该 Tweet 关联媒体。最多可包含 4 张图片、1 个动图 GIF 或 1 个视频。 注：媒体资产必须位于该账户的 Media Library。 注：通过仅提供参数但不赋值来取消设置（移除）。 类型：string 示例：13_1153584529292270722 |
| nullcast 可选 | 是否创建 nullcast（“仅推广”）Tweet。 类型：boolean 可能的取值：true、false |
| text 可选 | 状态更新的文本。 类型：string 示例：just setting up my twttr |
| name 可选 | Draft Tweet 的名称。最大长度：80 个字符。 类型：string 示例：Tweet with name |
示例请求
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被操作账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。类型：string 示例：18ce54d4x5t |
| draft_tweet_id 必填 | 你在请求中所操作的 Draft Tweet 的引用。类型：string 示例：994787835663155200 |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200
示例结果
POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id
在移动设备上预览草稿 Tweet。 请求成功后，会向已登录该已认证用户的每台设备发送通知。点击通知会打开时间线，用户可以查看并与该草稿 Tweet 互动，以测试自动播放、音量、全屏、视频网站卡片停靠等行为。 注意：设备内预览仅对接收通知的用户可见。 注意：通知仅会发送到 X 官方应用。资源 URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已验证的用户关联。 类型：string 示例：18ce54d4x5t |
| draft_tweet_id 必填 | 你在请求中要操作的 Draft Tweet 的引用。 类型：string 示例：996132315829948416 |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416
示例响应
图片会话卡片
card_uri 参数。
GET accounts/:account_id/cards/image_conversation
检索与当前账户关联的部分或全部图像对话卡的详细信息。资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 该投放账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| card_ids 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的图片会话卡片。最多可提供 200 个 ID。 类型：string 示例：59woh |
| count 可选 | 指定每个请求尝试检索的记录数。 类型：int 默认值：200 最小值、最大值：1、1000 |
| cursor 可选 | 指定用于获取下一页结果的游标。参见 Pagination 了解更多信息。 类型：string 示例：8x7v00oow |
| q 可选 | 可选查询参数，用于按 name 限定卡片。省略此参数以检索全部。最大长度：80 个字符。 注意：执行不区分大小写的前缀匹配。 类型：string 示例：night |
| sort_by 可选 | 按支持的属性进行升序或降序排序。参见 Sorting 了解更多信息。 类型：string 示例：created_at-asc |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的值：true、false |
| with_total_count 可选 | 包含 total_count 响应属性。 注意：此参数与 cursor 互斥。 注意：包含 total_count 的请求将有更低的速率限制，目前为每 15 分钟 200 次。 类型：boolean 默认值：false 可能的值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh
示例响应
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 使用的账户标识符。出现在资源路径中，通常在除 GET accounts 之外的所有 Advertiser API 请求中均为必填参数。指定的账户必须与已验证用户关联。 类型：string 示例：18ce54d4x5t |
| card_id 必填 | 你在请求中操作的图片会话卡片的引用。 类型：string 示例：59woh |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh
示例响应
POST accounts/:account_id/cards/image_conversation
创建与指定账户关联的新的图像会话卡片。 有关向我们的端点上传图像的实用信息，请参阅上传媒体。资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常除 GET accounts 外，所有 Advertiser API 请求都需要该参数。指定账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| first_cta 必填 | 第一个选项的号召性（CTA）话题标签。最大长度：20 个字符（不含 #）。 类型：string 示例：#ShareNow |
| first_cta_tweet 必填 | 点击第一个 CTA 时使用的 Tweet 文本。 类型：string 示例：I Heart @AdsAPI |
| media_key 必填 | 此卡片所用图片的 media key。 注意：图片必须位于账户的 Media Library 中。 注意：图片最小宽度为 800px，且宽高比为 1.91:1。 类型：string 示例：3_1151345051104991073 |
| name 必填 | 卡片名称。 类型：string 示例：image conversation card |
| thank_you_text 必填 | 点击 CTA 后显示的文本。最大长度：23 个字符。 类型：string 示例：Thank you |
| second_cta 有时必填 | 第二个选项的号召性（CTA）话题标签。最大长度：20 个字符（不含 #）。 类型：string 注意：当未设置 title 时为必填。 示例：#ShareAgain |
| second_cta_tweet 有时必填 | 点击第二个 CTA 时使用的 Tweet 文本。 注意：当已设置 second_cta 时为必填。 类型：string 示例：I Heart @AdsAPI Again |
| title 有时必填 | 卡片标题，显示在图片下方、CTA 上方。最大长度：23 个字符。 类型：string 注意：当未设置 second_cta 时为必填。 示例：Start a conversation |
| third_cta 可选 | 第三个选项的号召性（CTA）话题标签。最大长度：20 个字符（不含 #）。 类型：string 示例：#ShareMore |
| third_cta_tweet 有时必填 | 点击第三个 CTA 时使用的 Tweet 文本。 类型：string 注意：当已设置 third_cta 时为必填。 示例：I Heart @TwitterDev |
| fourth_cta 可选 | 第四个选项的号召性（CTA）话题标签。最大长度：20 个字符（不含 #）。 类型：string 示例：#ShareExtra |
| fourth_cta_tweet 有时必填 | 点击第四个 CTA 时使用的 Tweet 文本。 类型：string 注意：当已设置 fourth_cta 时为必填。 示例：I Heart @TwitterDev Again |
| unlocked_image_media_key 可选 | 在即时解锁场景中使用的图片 media_key。 这是一个只写字段。在响应中，API 会为该图片提供一个 X URL。 注意：图片必须位于账户的 Media Library 中。 注意：图片最小宽度为 800px，且宽高比为 5:2。 类型：string 示例：3_883112887618682880 |
| thank_you_url 可选 | 与致谢文本一起显示的 URL。 类型：string 示例：https://example.com/thankyou |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| card_id 必填 | 请求中所操作的图片会话卡片的标识引用。 类型：string 示例：4i0qg |
| first_cta 可选 | 第一个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不包含 #）。 类型：string 示例：#ShareNow |
| first_cta_tweet 可选 | 点击第一个 CTA 时要使用的 Tweet 文本。 类型：string 示例：I Heart @AdsAPI |
| second_cta 可选 | 第二个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不包含 #）。 类型：string 注意：当未设置 title 时为必填。 示例：#ShareAgain |
| second_cta_tweet 可选 | 点击第二个 CTA 时要使用的 Tweet 文本。 注意：当设置了 second_cta 时为必填。 类型：string 示例：I Heart @AdsAPI Again |
| third_cta 可选 | 第三个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不包含 #）。 类型：string 示例：#ShareMore |
| third_cta_tweet 可选 | 点击第三个 CTA 时要使用的 Tweet 文本。 类型：string 注意：当设置了 third_cta 时为必填。 示例：I Heart @TwitterDev |
| fourth_cta 可选 | 第四个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不包含 #）。 类型：string 示例：#ShareExtra |
| fourth_cta_tweet 可选 | 点击第四个 CTA 时要使用的 Tweet 文本。 类型：string 注意：当设置了 fourth_cta 时为必填。 示例：I Heart @TwitterDev Again |
| media_key 可选 | 在此卡片中使用的图片的媒体键。 注意：图片必须位于该账户的 媒体库 中。 注意：图片最小宽度为 800px，且宽高比为 1.91:1。 类型：string 示例：3_1151345051104991073 |
| name 可选 | 卡片名称。 类型：string 示例：moon card |
| thank_you_text 可选 | 点击 CTA 后显示的文本。最大长度：23 个字符。 类型：string 示例：Thank you |
| thank_you_url 可选 | 与感谢文本一同显示的 URL。 类型：string 示例：https://example.com/thankyou |
| title 可选 | 卡片标题，显示在图片下方、CTA 上方。最大长度：23 个字符。 类型：string 注意：当未设置 second_cta 时为必填。 示例：Start a conversation |
| unlocked_image_media_key 可选 | 在即时解锁场景中使用的图片 media_key。 此字段为仅写。在响应中，API 将为该图片提供一个 X URL。 注意：图片必须位于该账户的媒体库中。 注意：图片最小宽度为 800px，且宽高比为 5:2。 类型：string 示例：3_883112887618682880 |
示例请求
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card
示例响应
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被操作账户的标识符。该值出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：18ce54d4x5t |
| card_id 必填 | 你在请求中操作的图像会话卡片（image conversation card）的引用。类型：string 示例：4i0qe |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe
示例回复
媒体库
GET accounts/:account_id/media_library
获取与当前账户关联的部分或全部媒体库对象的详细信息。资源 URL
https://ads-api.x.com/12/accounts/:account_id/media_library
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| count 可选 | 指定每个单独请求尝试检索的记录数量。 类型：int 默认：20 最小/最大：1/50 |
| cursor 可选 | 指定用于获取下一页结果的游标。参见 Pagination 以了解更多信息。 类型：string 示例：c-1 |
| media_type 可选 | 将响应限定为所需的媒体类型。 类型：enum 可能的取值：GIF、IMAGE、VIDEO |
| q 可选 | 可选查询，用于按 name、title、file_name 和 description 字段限定资源范围。 注意：执行不区分大小写的术语匹配。 类型：string 最小/最大长度：1/255 |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。该值出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| media_key 必填 | 你在请求中要操作的媒体库对象的引用。 类型：string 示例：13_909110614026444802 |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802
示例响应示例
AMPLIFY_VIDEO 媒体类别的视频添加到媒体库时，它会自动作为 PREROLL account_media 资产可用。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/media_library
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 所使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| media_key 必填 | 已上传内容的 media_key。当指定了 media_category 时，POST media/upload 的响应会返回一个 media_key。 类型：string 示例：3_931236738554519552 |
| description 可选 | 发布为 Tweet 时显示在视频下方的描述。最大长度：200 个字符。默认情况下，Tweet 中不会显示该内容。要显示视频的 description，请在 POST accounts/:account_id/tweet 端点中使用 video_description 参数。 注意：仅可用于视频。 类型：string 示例：This is the description under the video. |
| file_name 可选 | 媒体库对象的文件名。最大长度：255。文件名可在 ads.x.com 的 Media Library 界面中每个媒体资产的媒体详情里看到。未设置 file_name 时将为空。 类型：string 示例：coffee.jpeg |
| name 可选 | 媒体库对象的名称。最大长度：100。这是 ads.x.com 的 Media Library 界面中每个媒体资产下方的标签。未设置 name 时，标签将显示为“Untitled”。 类型：string 示例：Latte |
| poster_media_key 可选 | 使用已上传图片的 media_key 为视频指定海报图。若未指定，将使用第一帧。 注意：仅可用于视频。 类型：string 示例：3_890599134483242005 |
| title 可选 | 发布为 Tweet 时显示在视频下方的标题（headline）。最大长度：70 个字符。默认情况下，Tweet 中不会显示该内容。要显示视频的 title，请在 POST accounts/:account_id/tweet 端点中使用 video_title 参数。 注意：仅可用于视频。 类型：string 示例：Video title |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 所使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已通过身份验证的用户关联。 类型：string 示例：18ce54d4x5t |
| media_key 必填 | 你在请求中操作的媒体库对象的引用。 类型：string 示例：16_844800354743074820 |
| description 可选 | 在发布为 Tweet 时显示在视频下方的描述。最大长度：200 个字符。默认情况下不会在 Tweet 中呈现。要显示视频的 description，请在 POST accounts/:account_id/tweet 端点中使用 video_description 参数。注意：仅适用于视频。 类型：string 示例：This is the description under the video. |
| file_name 可选 | 媒体库对象的文件名。最大长度：255。文件名可在 ads.x.com 的 Media Library 界面中每个媒体资产的媒体详情中查看。未设置 file_name 时，此字段为空。 类型：string 示例：coffee.jpeg |
| name 可选 | 媒体库对象的名称。最大长度：100。这是 ads.x.com 的 Media Library 界面中每个媒体资产下方的标签。未设置 name 时，标签将显示为“Untitled”。 类型：string 示例：Latte |
| poster_media_key 可选 | 使用已上传图片的 media_key 为视频指定封面图像。注意：仅适用于视频。 类型：string 示例：3_885003359340375465 |
| title 可选 | 在发布为 Tweet 时显示在视频下方的标题（headline）。最大长度：70 个字符。默认情况下不会在 Tweet 中呈现。要显示视频的 title，请在 POST accounts/:account_id/tweet 端点中使用 video_title 参数。注意：仅适用于视频。 类型：string 示例：Video title |
示例请求
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space
示例响应
资源 URL
https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被操作广告账户的标识符。该值出现在资源路径中，且通常是除GET accounts外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| media_key 必填 | 你在请求中所操作的媒体库对象的引用。 类型：string 示例：7_860318603387600896 |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896
示例回复
投票卡
GET accounts/:account_id/cards/poll
获取与当前账号关联的部分或全部投票卡片的详细信息。资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/poll
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 使用的账户标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| card_ids 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的投票卡片。最多可提供 200 个 ID。 类型：string 示例：57i77 |
| count 可选 | 指定每个单次请求尝试检索的记录数量。 类型：int 默认值：200 最小值、最大值：1、1000 |
| cursor 可选 | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 类型：string 示例：8x7v00oow |
| q 可选 | 用于按 name 限定卡片的可选查询。省略此参数将检索全部。最大长度：80 个字符。注意：执行不区分大小写的前缀匹配。 类型：string 示例：night |
| sort_by 可选 | 按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 类型：string 示例：created_at-asc |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true、false |
| with_total_count 可选 | 包含 total_count 响应属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将具有更低的速率限制，目前为每 15 分钟 200 次。 类型：boolean 默认值：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| card_id 必填 | 请求中所操作的投票卡片的标识。 类型：string 示例：57i8t |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true，false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t
示例回复
POST accounts/:account_id/cards/poll
创建一个与指定账户关联的新的投票卡片。此端点支持创建带图片、带视频或无媒体的投票卡片。包含媒体的投票称为 Media Forward Polls。 注意：Media Forward Polls 产品处于测试阶段，且需要启用PROMOTED_MEDIA_POLLS 账户功能。
注意：投票卡片无法更新（PUT）。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/poll
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 使用的账户标识符。出现在资源路径中，一般为除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| duration_in_minutes 必填 | 投票保持开放的时长（分钟）。在达到指定的 duration_in_minutes 后，投票将关闭，不再接受投票。这对应响应中的 end_time。 注意：计时在卡片创建时即开始，而非添加到 Tweet 时开始。 类型：int 取值范围：最小 5，最大 10080 |
| first_choice 必填 | 第一个投票选项。最大长度：25 个字符。 类型：string 示例：One |
| name 必填 | 卡片名称。 类型：string 示例：poll card |
| second_choice 必填 | 第二个投票选项。最大长度：25 个字符。 类型：string 示例：Two |
| fourth_choice 可选 | 第四个投票选项。最大长度：25 个字符。 注意：使用此参数时，必须同时设置第一、第二和第三个选项。 类型：string 示例：Four |
| media_key 可选 | 将用于此卡片的媒体库图片或视频的 media_key。 这是只写字段。在响应中，API 将提供该媒体的 X URL。 注意：图片或视频必须位于该账户的媒体库中。 注意：图片最小宽度为 800px，且宽高比需为 1.91:1。 |
| third_choice 可选 | 第三个投票选项。最大长度：25 个字符。 注意：使用此参数时，必须设置第一和第二个选项。 类型：string 示例：Three |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：18ce54d4x5t |
| card_id 必填 | 本次请求中所操作的投票卡片的引用。类型：string 示例：57i9t |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t
示例回复
片头前置广告行动号召
GET accounts/:account_id/preroll_call_to_actions
检索当前账户下各个投放项所关联的部分或全部前贴片号召性用语（CTA）的详细信息。资源 URL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| line_item_ids 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为与指定广告项关联的前贴片 CTA。最多可提供 200 个 ID。 类型：string 示例：8v53k |
| count 可选 | 指定每个请求尝试检索的记录数。 类型：int 默认值：200 最小值、最大值：1、1000 |
| cursor 可选 | 指定用于获取下一页结果的游标。参见分页了解详情。 类型：string 示例：8x7v00oow |
| preroll_call_to_action_ids 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的前贴片 CTA。最多可提供 200 个 ID。 类型：string 示例：8f0 |
| sort_by 可选 | 按受支持的属性进行升序或降序排序。参见排序了解详情。 类型：string 示例：created_at-asc |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true、false |
| with_total_count 可选 | 包含 total_count 响应属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将有更低的速率限制，目前为每 15 分钟 200 次。 类型：boolean 默认值：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所需的参数。指定的账户必须与已通过验证的用户关联。 类型：string 示例：18ce54d4x5t |
| preroll_call_to_action_id 必填 | 你在该请求中操作的前贴片号召性用语（preroll call to action）的引用。 类型：string 示例：8f0 |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0
示例回复
POST accounts/:account_id/preroll_call_to_actions
为PREROLL_VIEWS 明细项设置可选的号召性用语（CTA）。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 已授权账户的标识符。该值出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| call_to_action 必填 | 广告中按钮的 CTA 文案。 类型：enum 可能的取值：GO_TO、SEE_MORE、SHOP、VISIT_SITE、WATCH_NOW |
| call_to_action_url 必填 | 点击 CTA 按钮后重定向用户的 URL。 类型：string 示例：https://www.x.com |
| line_item_id 必填 | 请求中所操作投放单元（line item）的引用。 类型：string 示例：8v53k |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.x.com
示例回复
PREROLL_VIEWS 订单项更新可选的号召性用语（CTA）。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| preroll_call_to_action_id 必填 | 此请求中所操作的前贴片 CTA 的引用。 类型：string 示例：8f0 |
| call_to_action 可选 | 广告中按钮显示的 CTA 文本。 类型：enum 可选值：GO_TO、SEE_MORE、SHOP、VISIT_SITE、WATCH_NOW |
| call_to_action_url 可选 | 点击 CTA 按钮后用于重定向用户的 URL。 类型：string 示例：https://www.x.com |
示例请求
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW
示例响应
资源 URL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已通过身份验证的用户关联。类型：string 示例：18ce54d4x5t |
| preroll_call_to_action_id 必填 | 此请求中所操作的前贴片 CTA 的引用。类型：string 示例：8f0 |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0
示例回复
定时发布的 Tweet
GET accounts/:account_id/scheduled_tweets
检索与当前账户关联的部分或全部已安排的 Tweet 详情。资源 URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 账户标识符。该值出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已验证用户关联。 类型：string 示例：18ce54d4x5t |
| count 可选 | 指定每个请求尝试获取的记录数量。 类型：int 默认值：100 最小值/最大值：1/200 |
| cursor 可选 | 指定用于获取下一页结果的游标。有关分页的更多信息，请参阅 Pagination。 类型：string 示例：c-j3cn6n40 |
| user_id 可选 | 指定要为其检索计划发布的 Tweet 的用户。未设置时，默认为该账户上的 FULL 可推广用户。 类型：long 示例：756201191646691328 |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1
示例响应
资源 URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。类型：string 示例：18ce54d4x5t |
| scheduled_tweet_id 必填 | 本次请求所操作的 Scheduled Tweet 的引用。类型：string 示例：917438609065623552 |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552
示例响应
POST accounts/:account_id/scheduled_tweets
为该账号的完整可推广用户（默认）或通过as_user_id 参数指定的用户创建一个 Scheduled Tweet。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 所使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| scheduled_at 必填 | Tweet 计划发布（上线）的时间，采用 ISO 8601 格式。 注意：Tweet 最多只能安排在未来一年内。 注意：Tweet 仅支持按分钟粒度安排；秒数将被忽略。 类型：string 示例：2017-12-31T23:59:00Z |
| as_user_id 必填 | 代表其发布 Tweet 的广告主的用户 ID。广告主必须通过 ads.x.com 授予你的账号访问其广告账户的权限。此权限允许你使用自己账号的 OAuth 令牌调用 API，而非广告主的。 类型：long 示例：756201191646691328 |
| text 视情况必填 | 状态更新的文本。若未指定 media_keys，则必填。 类型：string 示例：just setting up my twttr |
| card_uri 可选 | 使用任一卡片响应中的 card_uri 值（如可用）将卡片与 Tweet 关联。 类型：string 示例：card://855591459410511943 |
| media_keys 可选 | 通过指定以逗号分隔的标识符列表，将媒体与 Tweet 关联。可包含最多 4 张图片、1 个动画 GIF 或 1 个视频。 注意：媒体资产必须位于该账户的 Media Library 中。 类型：string 示例：13_1153584529292270722 |
| nullcast 可选 | 是否创建 nullcast（“仅推广”）Tweet。 类型：boolean 默认值：true 可能的取值：true、false |
| name 可选 | 计划发布的 Tweet 的名称。最大长度：80 个字符。 类型：string 示例：Tweet with name |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 使用的账户标识符。出现在资源路径中，通常是除 GET accounts 以外所有 Advertiser API 请求必需的参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| scheduled_tweet_id 必填 | 你在请求中操作的 Scheduled Tweet 的引用。 类型：string 示例：870321875435442177 |
| card_uri 可选 | 使用任一卡片响应中的 card_uri 值（如果可用）将卡片与 Tweet 关联。 注意：通过仅指定参数而不提供值来清除（移除）。 类型：string 示例：card://875146925316386347 |
| media_keys 可选 | 通过指定逗号分隔的标识符列表将媒体与 Tweet 关联。最多可包含 4 张图片、1 个动图（GIF）或 1 个视频。 注意：媒体资产必须位于该账户的 Media Library 中。 注意：通过仅指定参数而不提供值来清除（移除）。 类型：string 示例：13_1153584529292270722 |
| nullcast 可选 | 是否创建 nullcast（或“仅用于推广”）Tweet。 类型：boolean 可选值：true、false |
| scheduled_at 可选 | Tweet 计划发布（上线）的时间，采用 ISO 8601 格式。 类型：string 示例：2017-12-31T23:59:59Z |
| text 可选 | 状态更新的文本内容。 类型：string 示例：just setting up my twttr |
| name 可选 | Scheduled Tweet 的名称。最大长度：80 个字符。 类型：string 示例：Tweet with name |
示例请求
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已通过验证的用户关联。 类型：string 示例：18ce54d4x5t |
| scheduled_tweet_id 必填 | 你在该请求中操作的 Scheduled Tweet 的引用。 类型：string 示例：870321875435442177 |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776
示例回复
Tweet 预览
GET accounts/:account_id/tweet_previews
预览已发布、已计划或草稿状态的 Tweet。- 支持在单个 API 请求中预览多个 Tweet，最多 200 条
- 准确、实时地渲染 Tweet 的布局和样式
- 支持所有最新格式和卡片类型
- 返回一个 iframe
资源 URL
https://ads-api.x.com/12/accounts/:account_id/tweet_previews
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账号的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账号必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| tweet_ids 必填 | 以逗号分隔的标识符列表。最多可提供 200 个 ID。 注意：这些 ID 应与指定的 tweet_type 相对应。例如，如果传入的是 Scheduled Tweet 的 ID，且指定了 tweet_type=PUBLISHED，将不会返回该 ID 的预览。 类型：long 示例：1122911801354510336,1102836745790316550 |
| tweet_type 必填 | 所指定 tweet_ids 对应的 Tweet 类型。 类型：enum 可能的取值：DRAFT、PUBLISHED、SCHEDULED |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED
示例回答
Tweets
GET accounts/:account_id/tweets
检索该账户的完整“可投放用户”（默认）或由user_id 参数指定的用户的 Tweet 详情。该用户可以是账户下的任一可投放用户。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/tweets
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 杠杆账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：18ce54d4x5t |
| tweet_type 必填 | 指定所给 tweet_ids 对应的 Tweet 类型。类型：enum 可选值：DRAFT、PUBLISHED、SCHEDULED |
| count 可选 | 指定每个请求尝试检索的记录数。类型：int 默认值：200 取值范围：1–1000 |
| cursor 可选 | 指定用于获取下一页结果的游标。更多信息参见 Pagination。类型：string 示例：AAAAAFhLRpQLNF-sGBSgAA |
| include_mentions_and_replies 可选 | 是否从可用的 Tweets 列表中过滤提及和回复。类型：boolean 默认值：false 可选值：true、false |
| name 可选 | 按 name 限定 Tweets 的可选查询。省略此参数以检索全部。最大长度：80 个字符。注意：执行不区分大小写的前缀匹配。类型：string 示例：dtc |
| timeline_type 可选 | 返回 nullcast（又称“仅推广”）的 Tweets、有机 Tweets，或两者皆返回。类型：enum 默认值：NULLCAST 可选值：ALL、NULLCAST、ORGANIC |
| trim_user 可选 | 是否在 Tweet 响应中排除用户对象。启用时，返回的用户对象仅包含该 Tweet 作者的用户 ID。类型：boolean 默认值：false 可选值：true、false |
| tweet_ids 可选 | 以逗号分隔的标识符列表。最多可提供 200 个 ID。注意：这些 ID 应与指定的 tweet_type 对应。例如，如果传入的是已排期 Tweet 的 ID，则 tweet_type 必须为 SCHEDULED，该 Tweet 才会在响应中返回。类型：long 示例：1122911801354510336,1102836745790316550 |
| user_id 可选 | 指定要限定 Tweets 的用户。未设置时，默认为账户上的 FULL 可投放用户。类型：long 示例：756201191646691328 |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true
示例响应结果
POST accounts/:account_id/tweet
为账户的完整可推广用户（默认）或在as_user_id 参数中指定的用户创建一条 Tweet。支持创建暗投（默认）和自然 Tweet。暗投 Tweet 不会出现在公共时间线中，也不会分发给关注者。两种类型都可用于广告系列。
如果经过身份验证的用户不是此账户的 FULL 可推广用户，请调用 GET accounts/:account_id/authenticated_user_access 端点以确定其是否有权代表该用户发布 Tweet。权限为 TWEET_COMPOSER 表示该用户可以使用此端点代表 FULL 可推广用户 创建暗投 Tweet。
当为媒体使用 upload.x.com 端点 时，请为 additional_owners 参数传入与此端点中 as_user_id 相同的 user_id 值。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/tweet
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| as_user_id 必填 | 代表其发布 Tweet 的广告主的用户 ID。广告主必须通过 ads.x.com 授予你的账号访问其广告账户的权限。此权限允许你使用自己账号的 OAuth 令牌调用 API，而非使用广告主的。 类型：long 示例：756201191646691328 |
| text 有时必填 | 状态更新的文本。若未指定 media_keys，则必填。 类型：string 示例：hello, world |
| card_uri 可选 | 使用任意 cards 响应中的 card_uri 值（如有）将卡片与该 Tweet 关联。 类型：string 示例：card://853503245793641682 |
| conversation_settings 可选 | 选择谁可以回复此 Tweet。被提及的任何人始终可以回复。 注意：此字段在 POST 请求的响应中不会返回，但在进行 GET 请求时会返回。 注意：此参数仅适用于 Ads API v8 及以上版本。 类型：enum 默认值：EVERYONE 可能的取值：EVERYONE、FOLLOWING、MENTIONED_USERS |
| media_keys 可选 | 通过指定以逗号分隔的标识符列表将媒体与该 Tweet 关联。最多可包含 4 张图片、1 个动图 GIF 或 1 个视频。 类型：string 示例：13_1153584529292270722 |
| name 可选 | Tweet 的名称。最大长度：80 个字符。 类型：string 示例：Tweet with name |
| nullcast 可选 | 是否创建 nullcast（或“仅推广”）Tweet。 注意：自然分发的 Tweet（nullcast=false）只能为已认证用户创建。 类型：boolean 默认值：true 可能的取值：true、false |
| trim_user 可选 | 是否在 Tweet 响应中排除用户对象。启用后，返回的用户对象仅包含该 Tweet 作者的用户 ID。 类型：boolean 默认值：false 可能的取值：true、false |
| tweet_mode 可选 | 响应应为兼容模式或扩展模式。更多信息请参见此处。 类型：string 可能的取值：compat、extended |
| video_cta 可选 | 视频的 CTA。 类型：enum 可能的取值：VISIT_SITE、WATCH_NOW |
| video_cta_value 可选 | 视频上对应 CTA 的值。 类型：string 示例：https://dev.x.com |
| video_description 可选 | 显示在视频下方的描述。最大长度：200 个字符。 类型：string 示例：集成 X 广告平台 |
| video_title 可选 | 显示在视频下方的标题。最大长度：70 个字符。 类型：string 示例：X Ads API |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet?text=hello, world&as_user_id=756201191646691328&trim_user=true
示例回应
name。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 所使用账户的标识符。该字段出现在资源路径中，一般是除 GET accounts 以外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| tweet_id 必填 | 本次请求所操作的 Tweet 的引用。 类型：long 示例：994747471329873920 |
| name 可选 | Tweet 的名称。最大长度：80 个字符。 类型：string 示例：Tweet with name |
示例请求
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name
示例响应
视频会话卡片
card_uri 参数：POST accounts/:account_id/tweet、POST statuses/update 或 POST accounts/:account_id/scheduled_tweets。
GET accounts/:account_id/cards/video_conversation
获取与当前账号关联的部分或全部视频会话卡的详细信息。资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型: string 示例: 18ce54d4x5t |
| card_ids 可选 | 通过指定以逗号分隔的标识符列表，仅返回所需的视频对话卡片。最多可提供 200 个 ID。 类型: string 示例: 5a86h |
| count 可选 | 指定每个请求尝试检索的记录数量。 类型: int 默认值: 200 最小值、最大值: 1、1000 |
| cursor 可选 | 指定用于获取下一页结果的游标。参见 Pagination 了解更多信息。 类型: string 示例: 8x7v00oow |
| q 可选 | 按 name 限定卡片的可选查询。省略此参数以检索全部。最大长度：80 个字符。 注意：执行不区分大小写的前缀匹配。 类型: string 示例: night sky |
| sort_by 可选 | 按支持的属性进行升序或降序排序。参见 Sorting 了解更多信息。 类型: string 示例: created_at-asc |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型: boolean 默认值: false 可能的取值: true、false |
| with_total_count 可选 | 包含 total_count 响应属性。 注意：此参数与 cursor 互斥。 注意：包含 total_count 的请求将具有更低的速率限制，目前为每 15 分钟 200 次。 类型: boolean 默认值: false 可能的取值: true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?card_ids=5a86h
示例回复
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 目标账户的标识符。该值出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已通过认证的用户关联。 类型：string 示例：18ce54d4x5t |
| card_id 必填 | 请求中所操作的视频会话卡片的标识引用。 类型：string 示例：4i0ya |
| with_deleted 可选 | 是否在结果中包含已删除项。 类型：boolean 默认值：false 可能的取值：true、false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h
示例响应
POST accounts/:account_id/cards/video_conversation
创建一个与指定账户关联的新视频对话卡片。 请参阅 Uploading Media，了解向我们的端点上传图像的实用信息。资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation
参数
| 名称 | 说明 |
|---|---|
| 账户_id必需 | 杠杆账户的标识符。显示在该资源内’在路径中使用，且通常为所有 Advertiser API 请求的必需参数，但不包括GET accounts（获取账户）。指定的账号必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| 首先_行动号召必填 | 第一个选项的号召性用语（CTA）标签。最大长度：20 个字符（不含 #）。类型：string 示例：#API |
| 第一_CTA_Tweet必填项 | 当第一个 CTA 被点击时使用的 Tweet 文本。类型：string 示例：广告 API |
| 媒体_密钥必填 | 用于此卡片的视频媒体键。注意事项: 视频必须在该账户中’s媒体库。注意: 需要 16:9 的宽高比。 类型：string 示例：13_1168079965037467209 |
| 名称必填项 | 卡片名称。 类型：字符串 示例：视频会话卡 |
| 谢谢_您_文本必填项 | 点击 CTA 后显示的文本。最大长度：23 个字符。类型：string 示例：开始构建 |
| 标题有时为必填项 | 卡片标题，显示在视频下方、CTA 上方。最大长度：23 个字符。类型：string注意：在以下情况下为必填second_cta为not已设置。示例：开发人员 |
| 秒_号召性用语有时为必填 | 第二个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不计入 #）。类型：字符串注意：在以下情况下为必填项标题为未已设置。示例：#再次分享 |
| 秒_号召性用语_Tweet有时必填 | 当用户点击第二个 CTA 时要使用的 Tweet 文本。注意事项：在以下情况下必填second_cta已设置。 类型：字符串 示例：我又爱上 @AdsAPI 了 |
| 发布者_媒体_键可选 | 用于此卡片的海报图片的媒体键。如果未指定，将使用第一帧。注意事项: 视频必须位于该账号的媒体库中’s媒体素材库。类型：long 示例：3_882726458191298561 |
| 第三_号召性用语可选项 | 第三个选项的号召性（CTA）话题标签。最大长度：20 个字符（不含 #）。 类型：string 示例：#分享更多 |
| 第三方_号召性用语（CTA）_Tweet有时必需 | 单击第三个 CTA 时使用的 Tweet 文本。类型：字符串注意：在以下情况下为必填third_cta已设置。示例：我爱 @TwitterDev |
| 第四条_CTA可选项 | 第四个选项的号召性（CTA）话题标签。最大长度：20 个字符（不计入 #）。 类型：string 示例：#ShareExtra |
| 第四个_号召性用语_Tweet有时为必填 | 点击第四个 CTA 时将使用的 Tweet 文本。类型：string注意事项：仅在以下情况下必填fourth_cta已设置。示例：我又爱上了 @TwitterDev |
| 感谢_您_URL可选项 | 与致谢文本一同显示的 URL。类型：string 示例：https://example.com/thankyou |
| 已解锁_图像_媒体_密钥可选 | Amedia_key的 media_key，对应将在即时解锁场景中使用的图像。此字段为仅写字段。在响应中，API 将为该图像返回一个 X URL。注意: 图像必须在该账号中’的媒体库。类型: string 示例：3_883112887618682880 |
| 已解锁_视频_媒体_密钥可选 | 视频的标识符，来自GET accounts/:account_id/media_library将在即时解锁场景中使用的 endpoint。 类型：string 示例：13_867520357225418752 |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?first_cta=#APIs&first_cta_tweet=Ads API&name=video conversation card&thank_you_text=Build it&title=Developers&media_key=13_958388276489895936
示例响应
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id
参数
| 名称 | 说明 |
|---|---|
| 帐户_id必填项 | 杠杆账户的标识符。出现在该资源内’的路径中，且通常在所有广告主 API 请求中都是必填参数，但不包括GET accounts。指定的帐号必须与已认证用户关联。 类型：string 示例：18ce54d4x5t |
| 卡片_id必填项 | 在请求中所使用的视频会话卡片的引用。类型：string 示例：5a86h |
| 首先_CTA可选 | 第一个选项的号召性（CTA）话题标签。最大长度：20 个字符（不计入“#”）。类型：string 示例：# API |
| 首先_CTA_Tweet可选项 | 当用户点击第一个 CTA 时要使用的 Tweet 文本。 类型：string 示例：广告 API |
| 秒_号召性用语可选项 | 第二个选项的号召性（CTA）话题标签。最大长度：20 个字符（不计入“#”）。类型：字符串注意：在以下情况下为必填title是not已设置。示例：#再次分享 |
| 秒_行动号召_Tweet可选 | 当点击第二个 CTA 时所使用的 Tweet 文本。注意：在以下情况下为必填second_cta已设置。 类型：字符串 示例：我又爱上了 @AdsAPI |
| 第三_号召性用语可选 | 第三个选项的号召性用语（CTA）标签。最大长度：20 个字符（不含 #）。 类型：string 示例：#分享更多 |
| 第三方_CTA_Tweet可选项 | 当点击第三个 CTA 时所使用的 Tweet 文本。类型：string注意：在以下情况时必填third_cta已设置。示例：我爱 @TwitterDev |
| 第四个_号召性用语可选项 | 第四个选项的号召性（CTA）主题标签（hashtag）。最大长度：20 个字符（不包括“#”）。 类型：string 示例：#分享加量 |
| 第四_号召性用语_Tweet可选项 | 当点击第四个 CTA 时要使用的 Tweet 文本。类型：字符串注意：在以下情况下为必填fourth_cta已设置。示例：我又爱上了 @TwitterDev |
| 媒体_密钥（可选） | 此卡片中所用视频的媒体密钥。注意：该视频必须在该账户中’s媒体库。注释: 需要使用 16:9 的宽高比。 类型：string 示例：13_1168079965037467209 |
| 名称可选 | 卡片名称。 类型：string 示例：开发者卡片 |
| 发布者_媒体_密钥（可选） | 用于此卡片的海报图像的 media key。若未指定，将使用第一帧。注意: 视频必须在该账号下’s媒体资源库。 类型：long 示例：3_882726458191298561 |
| 感谢_您_文本（可选） | 点击 CTA 后显示的文本。最长 23 个字符。 类型：string 示例：构建它 |
| 感谢_您_url可选项 | 与感谢文本一同显示的 URL。类型：string 示例：https://example.com/thankyou |
| 标题可选 | 卡片的标题，显示在视频下方、CTA 上方。最大长度：23 个字符。类型：string注意：在以下情况下为必填second_cta为not设置。示例：开始会话 |
| 已解锁_图像_媒体_键（可选） | Amedia_key将用于“即时解锁”场景的图像。这是一个只写字段。在响应中，API 会为该图像提供一个 X 的 URL。注意事项: 图像必须存于该账户’的媒体库。类型：string 示例：3_883112887618682880 |
| 已解锁_视频_媒体_密钥可选（非必填） | 来自…的视频标识符GET accounts/:account_id/media_library将在即时解锁场景中使用的端点。类型：string 示例：13_867520357225418752 |
示例请求
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card
示例响应
资源 URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 目标账户的标识符。该参数出现在资源路径中，通常在除GET accounts外的所有 Advertiser API 请求中都是必需的。指定的账户必须与已通过身份验证的用户关联。 类型：string 示例：18ce54d4x5t |
| card_id 必填 | 你在请求中所操作的视频会话卡片的引用。 类型：string 示例：4i0ya |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/4i0ya