图像对话卡片

注意:要将卡片关联到推文,请通过 POST accounts/:account_id/tweetPOST statuses/updatePOST accounts/:account_id/scheduled_tweets 端点,使用 card_uri 参数来完成。

GET accounts/:account_id/cards/image_conversation

检索与当前账号关联的部分或所有图像对话卡片详细信息。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/image_conversation

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

card_ids
可选

通过指定以逗号分隔的标识符列表,将响应范围限定至所需的图像对话卡片。最多可提供 200 个 ID。

类型:string

示例:59woh

count
可选

指定每个不同请求尝试检索的记录数量。

类型:int

默认值:200
最小值、最大值:11000
cursor
可选

指定光标以获取下一页结果。参阅分页了解更多信息。

类型:string

示例:8x7v00oow

q
可选

可选查询,按 name 指定卡片范围。省略此参数可检索所有卡片。最大长度:80 个字符。

注意:执行不区分大小写的前缀匹配。

类型:string

示例:night

sort_by
可选

根据支持的属性,按升序或降序排序。参阅排序了解更多信息。

类型:string

示例:created_at-asc

with_deleted
可选

在请求中包含已删除的结果。

类型:boolean

默认值:false
可能值:truefalse
with_total_count
可选

包含 total_count 响应属性。

注意:不包含此参数和 cursor

注意:包含 total_count 的请求速率限制较低,目前设置为每 15 分钟 200 次。

类型:boolean

默认值:false
可能值:truefalse

请求示例

GET https://ads-api.twitter.com/10/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh

响应示例

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_ids": [
        "59woh"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "image conversation card",
      "first_cta": "#moon",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "thanks",
      "id": "59woh",
      "first_cta_tweet": "stars",
      "media_key": "3_957113581522141184",
      "created_at": "2018-01-27T04:58:42Z",
      "image_display_width": "1280",
      "card_uri": "card://923498485702009837",
      "title": "Full moon",
      "updated_at": "2018-01-27T04:58:42Z",
      "deleted": false,
      "card_type": "IMAGE_CONVERSATION"
    }
  ]
}

GET accounts/:account_id/cards/image_conversation/:card_id

检索与当前账号关联的特定图像对话卡片。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/image_conversation/:card_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

card_id
必需

请求中对正在操作的图像对话卡片的引用。

类型:string

示例:59woh

with_deleted
可选

在请求中包含已删除的结果。

类型:boolean

默认值:false
可能值:truefalse

请求示例

GET https://ads-api.twitter.com/10/accounts/18ce54d4x5t/cards/image_conversation/59woh

响应示例

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_id": "59woh",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "image conversation card",
    "first_cta": "#moon",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "thanks",
    "id": "59woh",
    "first_cta_tweet": "stars",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Full moon",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  }
}

POST accounts/:account_id/cards/image_conversation

创建与指定账号关联的新图像对话卡片。

请参见上传媒体,获取上传图像至我们端点的相关有用信息。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/image_conversation

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

first_cta
必需

第一个选项的行动号召 (CTA) 话题标签。最大长度:20 个字符(# 除外)。

类型:string

示例:#ShareNow

first_cta_tweet
必需

点击第一个 CTA 后要使用的推文文本。

类型:string

示例:I Heart @AdsAPI

media_key
必需

在本卡片中使用的图像媒体密钥。

注意:图像必须位于账号的媒体库

注意:图像最小宽度必须为 800 像素,且宽高比为 1.91:1(宽:高)。

类型:string

示例:3_1151345051104991073

name
必需

卡片名称。

类型:string

示例:image conversation card

thank_you_text
必需

点击 CTA 后要显示的文本。最大长度:23 个字符。

类型:string

示例:Thank you

second_cta
有时为必需

第二个选项的行动号召 (CTA) 话题标签。最大长度:20 个字符(# 除外)。

类型:string

注意:如果未 (not) 设置 title,则为必需。

示例:#ShareAgain

second_cta_tweet
有时为必需

点击第二个 CTA 后要使用的推文文本。

注意:如果 second_cta 已设置,则为必需。

类型:string

示例:I Heart @AdsAPI Again

title
有时为必需

卡片名称,将出现在图像下方和 CTA 上方。最大长度:23 个字符。

类型:string

注意:如果未 (not) 设置 second_cta,则为必需。

示例:Start a conversation

third_cta
可选

第三个选项的行动号召 (CTA) 话题标签。最大长度:20 个字符(# 除外)。

类型:string

示例:#ShareMore

third_cta_tweet
有时为必需

点击第三个 CTA 后要使用的推文文本。

类型:string

注意:如果 third_cta 已设置,则为必需。

示例:I Heart @TwitterDev

fourth_cta
可选

第四个选项的行动号召 (CTA) 话题标签。最大长度:20 个字符(# 除外)。

类型:string

示例:#ShareExtra

fourth_cta_tweet
有时为必需

点击第四个 CTA 后要使用的推文文本。

类型:string

注意:如果 fourth_cta 已设置,则为必需。

示例:I Heart @TwitterDev Again

unlocked_image_media_key
可选

图像的 media_key,将在立即解锁情景下使用。

此字段为只写字段。在响应中,API 将为此图像提供 Twitter URL。

注意:图像必须位于账号的媒体库。

注意:图像最小宽度必须为 800 像素,且宽高比为 5:2(宽:高)。

类型:string

示例:3_883112887618682880

thank_you_url
可选

要显示的 URL,其中带有感谢的文本。

类型:string

示例:https://example.com/thankyou

请求示例

POST https://ads-api.twitter.com/10/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

响应示例

{
  "data": {
    "name": "image conversation card",
    "first_cta": "#moon",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "thanks",
    "id": "59woh",
    "first_cta_tweet": "stars",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Full moon",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "name": "image conversation card",
      "first_cta": "#moon",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "thanks",
      "media_key": "3_957113581522141184",
      "account_id": "18ce54d4x5t",
      "first_cta_tweet": "stars",
      "image_display_width": "1280",
      "title": "Full moon",
      "card_type": "IMAGE_CONVERSATION"
    }
  }
}

PUT accounts/:account_id/cards/image_conversation/:card_id

更新属于当前账号的指定图像对话卡片。

请参见上传媒体,获取上传图像至我们端点的相关有用信息。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/image_conversation/:card_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

card_id
必需

请求中对正在操作的图像对话卡片的引用。

类型:string

示例:4i0qg

first_cta
可选

第一个选项的行动号召 (CTA) 话题标签。最大长度:20 个字符(# 除外)。

类型:string

示例:#ShareNow

first_cta_tweet
可选

点击第一个 CTA 后要使用的推文文本。

类型:string

示例:I Heart @AdsAPI

second_cta
可选

第二个选项的行动号召 (CTA) 话题标签。最大长度:20 个字符(# 除外)。

类型:string

注意:如果未 (not) 设置 title,则为必需。

示例:#ShareAgain

second_cta_tweet
可选

点击第二个 CTA 后要使用的推文文本。

注意:如果 second_cta 已设置,则为必需。

类型:string

示例:I Heart @AdsAPI Again

third_cta
可选

第三个选项的行动号召 (CTA) 话题标签。最大长度:20 个字符(# 除外)。

类型:string

示例:#ShareMore

third_cta_tweet
可选

点击第三个 CTA 后要使用的推文文本。

类型:string

注意:如果 third_cta 已设置,则为必需。

示例:I Heart @TwitterDev

fourth_cta
可选

第四个选项的行动号召 (CTA) 话题标签。最大长度:20 个字符(# 除外)。

类型:string

示例:#ShareExtra

fourth_cta_tweet
可选

点击第四个 CTA 后要使用的推文文本。

类型:string

注意:如果 fourth_cta 已设置,则为必需。

示例:I Heart @TwitterDev Again

media_key
可选

在本卡片中使用的图像媒体密钥。

注意:图像必须位于账号的媒体库

注意:图像最小宽度必须为 800 像素,且宽高比为 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

注意:如果未 (not) 设置 second_cta,则为必需。

示例:Start a conversation

unlocked_image_media_key
可选

图像的 media_key,将在立即解锁情景下使用。

此字段为只写字段。在响应中,API 将为此图像提供 Twitter URL。

注意:图像必须位于账号的媒体库。

注意:图像最小宽度必须为 800 像素,且宽高比为 5:2(宽:高)。

类型:string

示例:3_883112887618682880

请求示例

PUT https://ads-api.twitter.com/10/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card

响应示例

{
  "data": {
    "name": "moon card",
    "id": "59woh",
    "created_at": "2018-01-27T04:58:42Z",
    "card_uri": "card://923498485702009837",
    "updated_at": "2018-01-29T21:04:39Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "IMAGE_CONVERSATION",
      "card_id": "59woh",
      "name": "moon card"
    }
  }
}

DELETE accounts/:account_id/cards/image_conversation/:card_id

永久删除属于当前账号的指定图像对话卡片。

注意:此操作为硬删除。删除后,将无法恢复删除的卡片。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/image_conversation/:card_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

card_id
必需

请求中对正在操作的图像对话卡片的引用。

类型:string

示例:4i0qe

请求示例

DELETE https://ads-api.twitter.com/10/accounts/18ce54d4x5t/cards/image_conversation/4i0qe

响应示例

{
  "data": {
    "name": "image conversation card",
    "id": "4i0qe",
    "created_at": "2017-07-07T00:03:01Z",
    "updated_at": "2017-08-23T13:26:23Z",
    "deleted": true,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0qe",
      "card_type": "image_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}