크리에이티브

​

개요

크리에이티브는 캠페인에서 프로모션 대상으로 사용할 수 있는 모든 개체를 의미합니다. 포스트에는 텍스트, 이미지, GIF, 동영상 또는 카드가 포함될 수 있습니다. 카드는 이미지 또는 동영상을 포함할 수 있습니다.

이미지, GIF 또는 동영상 크리에이티브는 POST media/upload — 이미지만 지원하는 간단한 업로드 엔드포인트 — 또는 POST media/upload (chunked) 엔드포인트를 사용해 업로드합니다. 이러한 크리에이티브는 다음에 추가할 수 있습니다.

카드:

• POST accounts/:account_id/cards Tweets:
• POST accounts/:account_id/tweets - Tweet에 카드를 추가하려면 card_uri 매개변수를 사용합니다. 예약된 Tweet:
• POST accounts/:account_id/scheduled_tweets

카드에 대한 자세한 내용은 Cards 페이지를 참조하세요. Promoted Video 페이지에서는 동영상을 카드나 Tweet과 연결하는 방법에 대해 설명합니다.

​

카드

Ads API는 Tweet에 사용할 수 있는 여러 카드 type을 지원하며, 이렇게 생성된 Tweet은 캠페인에서 프로모션할 수 있습니다. 참고: 한 번 Tweet이 게시되면 카드 세부 정보는 공개적으로 표시됩니다. 여기에는 카드를 소유한 사용자에 대한 정보가 포함될 수 있습니다.

​

이미지

다음 이미지 사양은 Cards에 사용되는 에셋에 적용됩니다. 이미지는 3MB 이하여야 하며, 너비가 최소 800px이어야 합니다. 또한 다음과 같은 가로:세로 비율을 지원합니다.

• Website: 1:1 및 1.91:1
• Image App Download: 1:1 및 1.91:1
• Poll: 1.91:1
• Image Conversation: 1.91:1
• Image Direct Message: 1.91:1

지원되는 이미지 형식은 .bmp, .jpeg, .png입니다.

​

동영상

다음 동영상 사양은 Cards에 사용되는 에셋에 적용됩니다. 지원되는 가로:세로 비율은 다음과 같습니다.

• 비디오 웹사이트: 16:9 및 1:1
• 비디오 App 다운로드: 16:9 및 1:1
• 투표: 16:9
• 비디오 대화: 16:9
• 비디오 다이렉트 메시지: 16:9

​

프로모티드 비디오

이 문서는 Ads API를 통해 비디오를 업로드하고 프로모션하는 절차에 대한 간단한 개요를 제공합니다.

Ads API는 Tweets 내 프로모티드 비디오와 다음 카드에서의 프로모티드 비디오를 지원합니다.

• Video Website
• Video App Download
• Video Conversation

먼저 POST media/upload (chunked) 엔드포인트를 사용해 비디오를 업로드합니다. 그런 다음 media_id를 사용해 POST accounts/:account_id/videos 엔드포인트로 해당 비디오를 광고 계정에 연결합니다. 비디오의 id는 때때로 media_key라고도 하며 이후 요청에서 사용됩니다. 이는 정수형 값으로 시작하고, 그 뒤에 밑줄이 오며, 마지막에 긴 숫자 값이 오는 문자열입니다. 예시는 다음과 같습니다: 13_875943225764098048.

​

Tweet에서 Promoted Video 사용

Tweet을 생성하려면 동영상의 id와 함께 POST accounts/:account_id/tweet 엔드포인트를 사용하세요. 이 단계에서 동영상 제목, 설명, 콜투액션(CTA)도 함께 지정할 수 있습니다. 이 값들은 사용자에게 직접 노출됩니다.

​

카드 내 프로모티드 비디오

Video App Download 및 Video Conversation 카드는 포스터 이미지를 추가할 수 있습니다. 이러한 카드에서 사용할 이미지는 POST media/upload 엔드포인트를 사용해 업로드합니다.

다음 엔드포인트 중 하나를 사용해 카드를 생성합니다.

• 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에 연결됩니다.

​

일반 정보

API를 통한 동영상 업로드에 대한 자세한 안내는 Video Upload Guide를 참고하세요.

동영상은 프리롤 자산으로도 프로모션할 수 있습니다. 자세한 설명은 Video Views Pre-roll Objective Guide를 참고하세요.

• (2015-10-22 기준) 프로모션용 콘텐츠에 사용할 동영상을 업로드할 때는, POST media/upload (chunked) 엔드포인트에 대한 모든 INIT 명령 요청에서 media_category 매개변수 값을 amplify_video로 설정해야 합니다. 이 매개변수를 사용하면 동영상이 비동기적으로 사전 처리되어 프로모션용 콘텐츠에 사용할 수 있도록 준비됩니다. 동영상 업로드 후 비동기 처리 완료 여부는 STATUS 명령으로 확인할 수 있습니다.
• 현재 허용되는 프로모션 동영상의 최대 길이는 10분이며, 파일 크기는 500MB 이하여야 합니다.
• 업로드하는 동영상 형식은 mp4 또는 mov여야 합니다.
• 업로드된 동영상은 일반적으로 빠르게 처리되지만, 처리 시간은 동영상 길이와 파일 크기에 따라 달라질 수 있습니다.
• 업로드하는 포스터 이미지는 png 또는 jpg 형식이어야 합니다. 종횡비나 크기 요구 사항은 없지만, 포스터 이미지는 동영상 플레이어에 맞게 조정됩니다.

​

가이드

​

예약 Tweet

​

소개

Scheduled Tweets 기능을 사용하면 광고주나 사용자가 나중에 게시되도록 Tweet을 예약해 둘 수 있습니다. 이러한 Tweet을 생성하고 관리할 수 있을 뿐만 아니라, API를 통해 이 Tweet을 라인 아이템에 연결해, Tweet이 게시되면 프로모션되도록 설정할 수 있습니다. 이를 통해 광고주는 네이티브 Tweet을 미리 작성해두고, 주요 캠페인 시작 전에 크리에이티브를 사전에 계획할 수 있습니다. 예를 들어, 새로운 제품 발표와 동시에 바로 게시되도록 Tweet 크리에이티브를 미리 준비해두는 경우가 이에 해당합니다.

Scheduled Tweets API 엔드포인트에서 제공하는 전체 기능은 아래와 같습니다:

• 새로 예약할 Tweet 생성, 수정 및 조회
• Scheduled Tweet을 라인 아이템에 연결
• 기존 Scheduled Tweet 조회 및 관리
• Scheduled Tweet이 라이브 상태가 되면 라이브 Tweet id 조회

​

API Endpoints

위 기능과 관련된 엔드포인트 전체 목록은 다음과 같습니다:

​

예약된 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 보기

• GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id (기존 예약 Tweet 보기)

예약 Tweet은 “라이브” Tweet과는 별도의 엔터티이기 때문에, 이 Tweet을 생성하거나 수정할 때 두 가지 서로 다른 검증이 수행됩니다. 첫 번째 검증 규칙 세트는 예약 Tweet 생성 단계, 즉 다음 시점에 실행됩니다:

​

Scheduled Tweet 생성:

• 인증된 사용자가 지정된 @handle에 대해 유기적(organic) Tweet을 생성할 수 있는 권한이 있는지 확인합니다. Promoted-Only Tweet 생성 권한을 사용하려면 인증된 사용자가 Tweet composer permissions을 보유한 계정 사용자여야 합니다.
• scheduled_at 시간 기준으로 앞뒤 15분 구간 안에 생성되도록 예약된 Tweet이 30개를 초과하지 않는지 확인합니다. SCHEDULED_TWEET_LIMIT_EXCEEDED 오류 메시지는 동일한 향후 15분 시간대에 너무 많은 Scheduled Tweet이 예약되었음을 의미합니다. 광고주는 기존 Scheduled Tweet을 삭제하거나 scheduled_at 시간을 더 이르거나 늦은 시점으로 변경해야 합니다.

​

Scheduled Tweet가 “라이브” 상태가 되는 경우:

• 이러한 유효성 검사는 scheduled_at 시간에 실행되며, API에서 일반 Tweet을 생성할 때 적용되는 규칙과 동일합니다. 예를 들어, 예약된 Tweet에 이미지와 GIF가 모두 포함되어 있으면 해당 Scheduled Tweet은 게시되지 않고 scheduled_status 가 FAILED 로 설정됩니다

​

워크플로

새로운 예약된 Tweet 생성

새로운 예약된 Tweet은 POST accounts/:account_id/scheduled_tweets 엔드포인트를 사용해 생성할 수 있습니다. 이 엔드포인트에서는 scheduled_at 시간과, Tweet에 미디어 엔티티가 포함되지 않은 경우 Tweet의 text를 필수 파라미터로 요구합니다. 또한 이 엔드포인트는 as_user_id 파라미터를 사용해 다른 @handle을 대신하여 예약된 Tweet을 생성할 수 있는 옵션과, 카드(card_uri) 및 미디어(media_ids)를 추가할 수 있는 몇 가지 추가 옵션을 제공합니다. 참고로 하나의 Tweet에는 동일한 type의 엔티티만 포함될 수 있으며, 즉 Video, Gif 또는 Image 중 하나만 사용할 수 있습니다. nullcast 파라미터는 해당 Tweet이 “Promoted-Only” Tweet인지 여부를 제어합니다. 새로 생성되는 모든 예약된 Tweet은 기본적으로 “Promoted-Only”(nullcast=true)입니다. nullcast=false인 경우 오가닉(Organic) 예약된 Tweet이 생성됩니다.

예약된 Tweet이 성공적으로 생성되면, 응답에는 예약된 Tweet 자체의 고유 식별자를 나타내는 id 필드가 포함됩니다. 이 필드 외에도 tweet_id라는 또 다른 필드가 함께 반환됩니다. 이 필드는 초기에는 null이지만, Tweet이 실제로 게시되어 live 상태가 되면 해당 “live” Tweet의 ID로 채워집니다.

twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Happy Holidays!'

이렇게 하면 다음과 같은 예약된 Tweet이 생성됩니다:

{
  "request": {
    "params": {
      "text": "Happy Holidays!",
      "scheduled_at": "2017-12-24T23:59:00Z"
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "917507899668099072",
    "text": "Happy Holidays!",
    "user_id": "3271358660",
    "scheduled_status": "SCHEDULED",
    "id": 917507899668099100,
    "nullcast": true,
    "created_at": "2017-10-09T21:51:44Z",
    "scheduled_at": "2017-12-24T23:59:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T21:51:44Z",
    "tweet_id": null,
    "media_keys": []
  }
}

이 예약된 Tweet이 라이브 상태가 되면, tweet_id 필드에는 “라이브” Tweet의 ID가 설정됩니다.

예약된 Tweet 보기

GET accounts/:account_id/tweet_previews 엔드포인트는 이전 단계에서 얻은 예약된 Tweet의 id와 함께 사용하여 Tweet 미리 보기를 생성할 수 있습니다. API 응답에는 예약된 Tweet 미리 보기를 렌더링하는 데 즉시 사용할 수 있는 iframe URL이 포함됩니다. 관련 CSS와 이미지는 X를 통해 직접 제공됩니다.

twurl -H ads-api.x.com -X GET "/6/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072

{
  "request": {
    "params": {
      "tweet_type": "SCHEDULED",
      "tweet_ids": [
        "917507899668099072"
      ],
      "account_id": "18ce54bgxky"
    }
  },
  "data": [
    {
      "tweet_id": "1126633863155871744",
      "preview": "<\iframe class='tweet-preview' src='https://ton.smf1.x.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAK1WTW%2FjNhD9Kyyv9dqSZdmOgALJbhJsCyxaIDkUWBUEJY0lNhSpklRSN%2FV%2F71CyZbm297S%2BWJxPzpt5I71T9wbgaELeaW6AOygYxyN9rlryhW9JcEPmUbKIkuiG%2FBjgj8yD8IZOqChoEobz5TKK1ssojOP1KlwtFl7BrDMY4oIW%2FTatlMzB3z7JZ940W%2FJZS1Hwrf0Btc60Kve3oMmGSwsTWgjbSL7tXJjhqgSafA0mYfzHhIJywgmwNHmnFbeV4yU%2Bf0WN3daZlvtDa8Gw2htrdRCZXrlDU92aHIPStA2CKOekMrD5KaWVc02SztIZps%2Bh0rIAg27TXNcpJQYk2ii90VLqt7R3ht%2B4cQoMeVClUIAPd03Th01nvDfx0ClmoJFYk0aouGst82gqROaKskf03KCr7LLvXnXN02K3QTHFaziovYdH0seL5qswitfLZTBq6FGIRfSe9Lm1FTfkY%2BX%2FFcpPAlNRC7eufdFSY1%2BxASh84oo8YitzYXM9IZ%2FuaNcQ1HjMbQc61l0VXDmYlsJVbTYVGq0KwPCi2cf5tQFFnjR2zyDU6YycwX%2Fr3oRzvfKpwTaSZ8NfQUoU%2FUsetanxAV79VElhHbm1oIrSiILcvvgquqSN0Q7y8Uz2TQdjWa5bhZP8IUShEeh8IvIxkVB7SY%2FyKctaIL%2B0kgQrMp8n0SKJ10eWxZ4t%2FBXHUzg4idu6nOnNxsIQ1Yka2D9aDc0sQTNQPJP%2B2sgqvPUrGLERozL68ToNLRELvBj4VuZaOSOy1mmsdAi2dxaWOeyhlRzVl6TYozMnhHIjJLCM5y%2BlwaweHOn96afg%2FuHhnl60ETUvgR1HpJsQntkptrcuO0bOOhuLg1NBPfyH6Swrpw2W9O24rBu8kwH8DuEdns9Kv1hLc5rsxBaTLcN1HIdhHIVRuFov5wtMXH748vO2%2BP0jUzjFXE7%2FbMa3%2BFZl3z1ZxhWyjv2fwlfy9NaY6LhO0lm4WC3WcRSvlqO4UqiXYT7C%2B7vwcT7SWlFAxg3LtMHNfH2ODnZ4kIPVPRo9jnN1r5eDNup%2BIy2y5GxuDrQqYMNb6dje9or44HOyQYTnWs%2FXXoD7%2Ba8WrGO4hwZuK%2B2Qt%2F32tAPhB%2B4xt238qjVQtpIbuuvIP6wbjfAIhStncO3eZ0f9keMHmYHuo%2BCwFoJ%2BDfktdEF0JPfebbxgct30b%2BdhY%2B51u%2FGm2U2IR7rW%2FbJU%2FdcBfpEchHjwoO52%2FwENmVvErwgAAA%3D%3D'>"
    }
  ]
}

위에는 새로 생성된 예약 Tweet의 예시 화면이 표시되어 있습니다

예약 Tweet을 라인 아이템에 연결하기

예약 Tweet은 Organic Tweet 생성을 위해 사용할 수 있을 뿐만 아니라, 파트너가 “Promoted-Only” (nullcast=true) Tweet을 생성하도록도 허용하며, 둘 중 어느 것이든 라인 아이템에 연결할 수 있습니다. 이를 위해 POST accounts/:account_id/scheduled_promoted_tweets 엔드포인트도 제공합니다. 이 엔드포인트는 단일 API 호출에서 하나의 Promoted Scheduled Tweet만 라인 아이템에 연결할 수 있도록 허용합니다. 여러 개의 예약 Tweet을 동일한 라인 아이템에 연결하려면 여러 번의 API 호출이 필요합니다.

기존에 생성된 Scheduled Promoted Tweet은 수정할 수 없습니다.

twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072'

{
  "data": {
    "line_item_id": "a44qc",
    "id": "26576",
    "created_at": "2017-10-09T22:24:16Z",
    "updated_at": "2017-10-09T22:24:16Z",
    "scheduled_tweet_id": "917507899668099072",
    "tweet_id": null,
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "a44qc",
      "scheduled_tweet_id": 917507899668099100,
      "account_id": "aaaaa"
    }
  }
}

이 endpoint는 지정된 Scheduled Tweet과 라인 아이템 사이의 연관 관계만 생성합니다. 캠페인/라인 아이템의 플라이트 날짜가 현재 시점이 되면, 해당 라인 아이템은 자동으로 연결된 “live” Tweet 송출을 시작합니다. 이 단계에서는 Scheduled Tweet이 SCHEDULED 상태인지, 그리고 주어진 objective에 대해 해당 Scheduled Tweet이 유효한지만 검증하며, 그 외의 검증은 수행되지 않습니다. 라인 아이템과 Scheduled Tweet에 적용되는 나머지 검증 규칙은 Tweet이 “live” 상태가 될 때 실행됩니다.

캠페인 송출에 문제가 발생하지 않도록 하려면, Scheduled Tweet의 scheduled_at 시간이 캠페인/라인 아이템 플라이트 시작 날짜보다 앞서도록 설정하는 것이 좋습니다.

예를 들어, Scheduled Tweet이 캠페인 시작일 이후에 live 되도록 설정되어 있고(또한 단일 라인 아이템에 단 하나의 Tweet만 연관되어 있는 경우), 이때 캠페인은 ACTIVE 상태가 되지만 Scheduled Tweet이 아직 live가 아니기 때문에 송출 가능한 크리에이티브가 존재하지 않게 됩니다.

Scheduled Tweet 관리

나머지 endpoint 집합을 통해 API 사용자는 모든 Scheduled Tweet 및 Scheduled Promoted Tweet을 관리할 수 있습니다. 이러한 API는 선택적으로 특정 상태로 필터링된 모든 Scheduled Tweet의 리스트를 반환하거나, id로 특정 Scheduled Tweet을 조회하는 데 사용할 수 있습니다.

​

예약된 Tweet이 라이브 상태가 되면 어떻게 되나요?

특정 예약된 Tweet이 라이브 상태가 되려 할 때, 다시 말해 scheduled_at 시점에 다음과 같은 업데이트가 이루어집니다:

• “라이브(live)” Tweet이 생성되지만, 최대 1초까지 지연(latency)이 발생할 수 있습니다.
• tweet_id가 다음 엔터티에 추가됩니다:
• Scheduled Tweet
• Promoted Scheduled Tweet
• 새로운 Promoted Tweet 엔터티가 생성됩니다.

​

모범 사례

예약된 Tweet을 생성하거나 프로모션할 때는 다음 모범 사례를 권장합니다.

• 예약된 Tweet을 생성할 때 해당 Tweet이 유효한지 확인하세요 (예: 하나의 Tweet에는 이미지, 동영상, GIF 중 하나만 포함할 수 있으며, 세 가지를 조합해서 사용할 수는 없습니다)
• 캠페인 플라이트 날짜(즉, start_time 및 end_time)가 예약된 Tweet의 scheduled_at 시간과 일치하는지 확인하세요
• 예약된 Tweet은 최대 1년(365일) 이내의 시점으로만 예약해야 합니다
• 현재 예약된 Tweet에 대해서는 Tweet 미리보기가 지원되지 않습니다(생성 전에 예약된 Tweet을 미리 확인하는 기능)

​

미디어 라이브러리

​

소개

Media Library 엔드포인트는 X Ads 계정에서 이미지, GIF, 동영상을 관리할 수 있는 기능을 제공합니다. 라이브러리의 미디어 에셋은 게시물(Tweet)과 카드 생성에 사용할 수 있습니다. 또한 여러 creatives에서 재사용할 수 있어, 동일한 에셋을 여러 번 업로드하지 않아도 됩니다.

​

API 엔드포인트

• POST media/upload (미디어 업로드) 또는 POST media/upload (chunked) (청크 단위로 미디어 업로드)
• POST accounts/:account_id/media_library (Media Library에 미디어를 추가)

​

라이브러리에 추가하기

라이브러리에 미디어를 추가하는 과정은 두 단계로 구성됩니다. 먼저, POST media/upload 엔드포인트 또는 POST media/upload (chunked) 엔드포인트 세트를 사용해 미디어 자산을 업로드합니다. (당사의 멀티파트 업로드 방식에 대한 자세한 내용은 Chunked media upload 가이드를 참조하세요.)

twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"

{
   "media_id":966947208837742592,
   "media_id_string":"966947208837742592",
   "size":74194,
   "expires_after_secs":86400,
   "image":{
      "image_type":"image/jpeg",
      "w":800,
      "h":418
   }
}

다음으로 미디어 ID를 사용하여 POST accounts/:account_id/media_library 엔드포인트를 통해 해당 미디어를 광고 계정의 라이브러리에 추가합니다.

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte"

{
   "request":{
      "params":{
         "name":"Latte",
         "file_name":"latte.jpeg",
         "media_category":"TWEET_IMAGE",
         "account_id":"18ce54d4x5t",
         "media_key":966947208837742592
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

참고: 업로드 직후 이미지, GIF 또는 동영상을 바로 Tweet에 게시하면 해당 미디어도 라이브러리에 추가됩니다.

​

요청 매개변수

모든 Media Library POST 요청에는 미디어 식별자가 필요합니다. 이 값은 업로드 단계에서 반환됩니다. 위의 예시처럼 media_id를 사용할 때에는 media_category도 반드시 지정해야 합니다. 가능한 카테고리 값은 네 가지입니다: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE, TWEET_VIDEO.

선택적으로, Media Library의 객체에 name 및 file_name 값을 설정할 수 있습니다. 이 속성들은 라이브러리에서 서로 다른 미디어 변형본을 사용자가 구분하는 데 도움이 됩니다.

동영상의 경우, title과 설명을 설정하는 것도 가능합니다. 이 값들은 POST accounts/:account_id/tweet 엔드포인트에서 video_title 및 video_description 요청 매개변수로 전달되도록 되어 있습니다. Tweet에서 이 텍스트는 동영상 아래에 표시됩니다.

​

속성

Media Library는 media_key라는 개념을 공식적으로 도입합니다. 이는 라이브러리 내 객체에 대한 고유 식별자입니다. media key는 다음과 같은 형식의 문자열 값입니다: 13_875943225764098048. 이러한 media key는 모든 카드 엔드포인트에서 지원됩니다.

추가로, Media Library 응답에는 문자열로 표현된 media_id가 포함됩니다. 이는 현재 media key를 허용하지 않는 리소스에 대해 제공됩니다: Tweets, Tweet preview, 그리고 Scheduled Tweets. 우리는 media key가 모든 곳에서 지원되도록 작업을 진행 중입니다.

aspect_ratio 속성은 GIF 및 동영상에 대해 반환됩니다. 이는 특정 가로세로 비율만 허용하는 카드에서 사용할 미디어를 필터링하는 데 사용할 수 있습니다.

*이러한 엔드포인트는 media key인 video_id 파라미터를 지원합니다.

​

사용 방법

이 섹션에서는 다음 이미지를 Tweet에 포함하고, 웹사이트 카드를 생성하는 데 사용합니다.

twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592"

{
   "request":{
      "params":{
         "account_id":"18ce54d4x5t",
         "media_key":"3_966947208837742592"
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

Tweet

media_keys를 사용해 이미지를 참조하여 Tweet을 생성할 수 있습니다.

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true"

{
   "data":{
      "created_at":"Fri Feb 23 08:20:05 +0000 2018",
      "id":966950781302665218,
      "id_str":"966950781302665218",
      "text":"coffee https://t.co/T772Hx5GNT",
      "truncated":false,
      "entities":{
         "hashtags":[

         ],
         "symbols":[

         ],
         "user_mentions":[

         ],
         "urls":[

         ],
         "media":[
            {
               "id":966947208837742592,
               "id_str":"966947208837742592",
               "indices":[
                  7,
                  30
               ],
               "media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "url":"https://t.co/T772Hx5GNT",
               "display_url":"pic.x.com/T772Hx5GNT",
               "expanded_url":"https://x.com/apimctestface/status/966950781302665218/photo/1",
               "type":"photo",
               "sizes":{
                  "thumb":{
                     "w":150,
                     "h":150,
                     "resize":"crop"
                  },
                  "large":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "medium":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "small":{
                     "w":680,
                     "h":355,
                     "resize":"fit"
                  }
               }
            }
         ]
      },
      "source":"Ads API Internal Test App",
      "in_reply_to_status_id":null,
      "in_reply_to_status_id_str":null,
      "in_reply_to_user_id":null,
      "in_reply_to_user_id_str":null,
      "in_reply_to_screen_name":null,
      "user":{
         "id":756201191646691328,
         "id_str":"756201191646691328"
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":[
         2417045708
      ],
      "retweet_count":0,
      "favorite_count":0,
      "favorited":false,
      "retweeted":false,
      "possibly_sensitive":false,
      "scopes":{
         "followers":false
      },
      "lang":"en"
   },
   "request":{
      "params":{
         "as_user_id":756201191646691328,
         "text":"coffee",
         "account_id":"18ce54d4x5t",
         "media_keys":[
            966947208837742592
         ],
         "trim_user":true
      }
   }
}

웹사이트 카드

모든 카드용 엔드포인트는 media key를 지원합니다. 이미지의 media_key를 참조해 웹사이트 카드를 생성합니다.

twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards"

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

그런 다음 card_uri를 사용해 이 card를 Tweet과 연결합니다.

​

카드 식별

​

소개

Cards는 미디어를 사용하는 맞춤형 광고 형식으로, 웹사이트, App 또는 다이렉트 메시지 시작과 같은 특정 사용자 참여를 유도하는 행동 유도(call to action)와 연계할 수 있습니다. Cards는 Tweet, 예약된 Tweet 또는 초안 Tweet에 추가될 수 있습니다.

Cards는 Tweet 객체 내에서 두 가지 방식 중 하나로 참조될 수 있습니다. card의 card_uri로 참조되거나 preview_url로 참조될 수 있습니다. 각각의 예시 값은 아래와 같습니다.

card_uri	preview_url
card://1043282691834048513	https://cards.x.com/cards/18ce54d4x5t/68w3s

참고: Ads API 버전 3부터 새로 생성된 card에 대해서는 card_uri만 생성되어 cards 응답에 반환됩니다.

참고: Ads API 버전 5부터 cards 응답에는 더 이상 preview_url이 반환되지 않습니다.

Tweet 객체 응답 내 참조 유형은 Tweet이 생성된 방식에 따라 달라집니다. 다시 말해, Tweet이 card_uri 요청 매개변수를 사용해 생성된 경우 응답에 card URI 값이 포함됩니다. 반면 preview_url이 Tweet 텍스트의 일부로 포함된 경우 응답에는 preview URL이 포함됩니다.

​

card_uri로 Tweet 식별하기

card의 URI 값을 사용해 생성된 Tweet의 경우, card_uri 응답 속성에서 해당 카드에 대한 참조를 확인할 수 있습니다. 아래 예시 응답은 GET accounts/:account_id/tweets 엔드포인트를 사용한 것입니다.

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
  "request": {
    "params": {
      "tweet_ids": [
        "1043551275923591168"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "source": "Ads API Internal Test App",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        15
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1043551275923591168",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 1043551275923591168,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "card_uri": "card://1043282691834048513",
      "full_text": "Tracking a card",
      "lang": "en",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1043551275923591168"
    }
  ]
}

Standard API를 사용하는 경우, 요청에 include_card_uri=true 쿼리 매개변수를 추가하세요.

어떤 엔드포인트를 사용하더라도 Tweet이 card URI를 사용해 생성된 경우에만 card_uri 응답 속성이 반환됩니다.

예약 및 초안 Tweet 객체의 경우, 응답에는 항상 card_uri 응답 속성이 포함됩니다.

​

preview_url로 Tweet 식별하기

Tweet 텍스트에 미리보기 URL을 포함해 Tweet을 생성한 경우, URL은 entities[“urls”][i][“expanded_url”]에서 확인할 수 있습니다(텍스트 필드에는 단축된 t.co URL이 포함됩니다). 여기서 i는 배열 인덱스이며, 하나의 Tweet에는 여러 개의 URL이 포함될 수 있습니다.

예약된 Tweet 및 초안 Tweet 객체의 경우, 미리보기 URL은 항상 text 필드에 나타납니다.

​

카드 가져오기

특정 카드에 대한 추가 정보를 가져오기 위해 두 가지 엔드포인트를 제공합니다: GET accounts/:account_id/cards/all 및 GET accounts/:account_id/cards/all/:card_id. 첫 번째 엔드포인트는 card_uri로 카드를 가져올 수 있고, 두 번째 엔드포인트는 카드 ID로 카드를 가져올 수 있습니다. 카드 ID는 preview_url의 끝부분에서 확인할 수 있습니다. 위 예시에서 ID는 68w3s입니다.

​

미디어 식별하기

​

소개

이미지, GIF, 동영상과 같은 미디어는 Tweet 및 카드에 추가할 수 있습니다. 또한 동영상은 프리롤 자산으로 사용할 수 있고 이미지는 X Audience Platform에서 프로모션용으로 사용할 수 있습니다. 이 섹션에서는 이러한 엔티티 전반에 걸쳐 미디어 참조를 식별하는 방법을 설명합니다.

미디어 식별자는 두 가지 유형이 있습니다: ID와 key입니다. 각 유형의 예시는 아래와 같습니다.

Media ID	Media key
1029825579531807971	13_1029825579531807971

Media key는 ID 앞에 숫자 접두사와 밑줄이 붙은 값입니다.

​

이미지

아래 표는 각 이미지 관련 리소스의 응답에서 현재 제공되는 식별자 유형과 해당 속성 이름을 보여줍니다.

Resource	Identifier	Attribute(s)
Image cards	None
Tweet	Both	entities["media"]["id_str"] entities["media"]["media_key"]
Scheduled Tweet	Both	media_ids and media_keys
Draft Tweet	Both	media_ids and media_keys
Account Media	None
Media Library	Both	media_id and media_key

Image cards와 Account Media 이미지에는 어떤 미디어 식별자에 대한 참조도 포함되지 않습니다. Tweet에는 미디어 ID만 포함됩니다. Scheduled 및 Draft Tweet에는 미디어 ID와 미디어 key가 모두 포함됩니다. Media Library 역시 둘 다 반환합니다.

Tweet의 경우, entities[“media”] 배열 내 객체의 id 및 id_str 필드는 미디어 ID에 해당합니다. 하나의 Tweet에 여러 이미지를 포함하는 경우, 각 미디어 엔티티에 대한 참조는 extended_entities[“media”]에서만 찾을 수 있습니다.

식별자에 대한 참조 외에도, 이미지의 URL에 접근할 수 있는지 여부가 중요한 경우가 많습니다.

Resource	Attribute(s)	Format
Image cards	image	.jpg
Tweet*	entities["media"][0]["media_url"] 또는 extended_entities["media"][i]["media_url"]	.jpg
Scheduled Tweet	None
Draft Tweet	None
Account Media	media_url	.jpg
Media Library	media_url	.jpg

• 이 URL 위치는 Tweet에 단일 이미지가 포함되어 있는지, 여러 이미지가 포함되어 있는지에 따라 달라집니다.

모든 Image card에는 X 이미지 URL을 포함하는 image라는 응답 속성이 있습니다. (이미지 앱 다운로드 카드의 경우 이름은 wide_app_image입니다.)

Tweet의 경우, 미디어 URL 위치는 미디어 유형과 사용 중인 endpoint에 따라 달라집니다. 단일 이미지를 가진 Tweet의 경우 URL은 entities[“media”][0][“media_url”]에서 찾을 수 있습니다. 이는 Ads API와 Standard API 모두에 해당합니다. 그러나 Tweet에 여러 이미지가 포함되어 있는 경우에는 URL을 extended_entities[“media”][i][“media_url”]에서만 찾을 수 있습니다. 이는 Standard API에서만 제공됩니다.

​

동영상

다음 표는 각 동영상 관련 리소스의 응답에서 현재 사용 가능한 식별자 유형과 해당 속성 이름을 보여줍니다.

리소스	식별자	속성
동영상 카드	둘 중 하나일 수 있음	video_content_id
동영상 설문조사 카드	없음
Tweet	둘 다	entities["media"]["id_str"] entities["media"]["media_key"]
예약된 Tweet	둘 다	media_ids 및 media_keys
임시 저장된 Tweet	둘 다	media_ids 및 media_keys
계정 미디어	미디어 키	video_id
미디어 라이브러리	둘 다	media_id 및 media_key

동영상 카드(동영상이 포함된 설문조사 카드는 예외)의 경우 응답 속성으로 video_content_id가 포함되지만, 반환되는 값의 유형에 일관성이 없습니다. 어떤 경우에는 미디어 ID이고, 다른 경우에는 미디어 키입니다.

동영상 URL에 접근하는 방법은 아래에 나와 있습니다.

리소스	속성	형식
동영상 카드	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을 제공합니다.

​

Media Library

때때로 미디어 에셋에 대한 추가 정보를 조회해야 할 때가 있습니다. 한 가지 사용 예로, 비디오 카드에서는 vmap URL 대신 mp4 URL을 가져와야 할 수 있습니다. 이는 Media Library에서 확인할 수 있습니다. 사용 가능한 정보에 대한 자세한 내용은 Media Library 가이드를 참고하세요. 광고 계정의 FULL 프로모션 대상 사용자에 속한 대부분의 에셋은 라이브러리에서 찾을 수 있습니다. 다만 몇 가지 예외가 있습니다.

미디어 가져오기

앞에서 설명했듯이, 이미지 카드는 media ID나 media key에 대한 참조를 포함하지 않습니다. 따라서 Media Library를 통해 해당 에셋을 가져올 수 없습니다. 이는 Account Media 이미지에도 동일하게 적용됩니다.

비디오 카드는 생성 전에 비디오 에셋이 Media Library(또는 이전의 Videos 리소스)에 포함되어 있어야 합니다. 따라서 이러한 에셋은 항상 Media Library에서 조회할 수 있습니다. 이는 Account Media PREROLL 에셋에도 동일하게 적용됩니다.

마지막으로, 트윗에 포함된 미디어는 항상 Media Library에 존재하는 것이 보장됩니다.

다음 표는 조회에 사용할 식별자가 리소스 응답에 포함되는지를 고려하여, Media Library에서 어떤 에셋을 조회할 수 있는지를 요약한 것입니다.

Resource	In the Media Library
Image cards	아니요
Video cards	예*
Tweets (any media)**	예
Scheduled Tweets	예
Draft Tweets	예
Account media images	아니요
Account media videos (PREROLL)	예

• video_content_id가 media key인 카드의 경우입니다. 값이 media ID인 경우에도 에셋은 Media Library에 존재하지만, 이를 조회하려면 해당 값 앞에 숫자 접두사와 밑줄을 붙여야 합니다. ** 트윗은 media ID만 반환합니다. 에셋이 Media Library에 존재하는 것은 보장되지만, 이를 가져오려면 media ID 앞에 숫자 접두사와 밑줄을 붙여야 합니다.

Account Media와의 상호작용

라이브러리에 추가된 미디어 에셋이 자동으로 Account Media 리소스에 추가되는 경우는 두 가지입니다.

• AMPLIFY_VIDEO 에셋이 Media Library에 추가되면, 자동으로 PREROLL 크리에이티브 타입의 Account Media 에셋으로 추가됩니다.
• 특정 크기(자세한 내용은 열거형 페이지의 “Creative Types” 참고)의 이미지를 Media Library에 추가하면, 자동으로 Account Media 에셋으로 추가됩니다. 크리에이티브 타입(예: INTERSTITIAL)은 이미지 크기에 따라 달라집니다.

​

Tweet

​

소개

X Ads API는 게시된 Tweet, 예약된 Tweet, 초안 Tweet 등 세 가지 유형의 Tweet을 지원합니다.

​

널캐스트된 Tweet

Tweet은 널캐스트(nullcasted, “Promoted-only”)이거나 오가닉(organic)일 수 있습니다. 널캐스트된 Tweet은 한 번 게시되면 공개 상태이긴 하지만 사용자의 공개 타임라인에는 표시되지 않습니다. 반면 오가닉 Tweet은 사용자의 팔로워에게 제공되며 사용자의 공개 타임라인에도 표시됩니다.

Tweet 생성

세 가지 Tweet 생성 엔드포인트 각각은 Boolean 타입의 nullcast 파라미터를 지원하며, 이를 통해 API 사용자는 널캐스트된 Tweet 또는 오가닉 Tweet을 생성할 수 있습니다. 널캐스트된 Tweet은 해당 사용자 본인 또는 그 사용자를 대신해 Tweet을 생성할 권한이 있는 누구나 생성할 수 있습니다. 오가닉 Tweet은 full promotable user만 생성할 수 있습니다.

Tweet 업데이트

예약 및 초안 Tweet의 nullcast 속성은 업데이트할 수 있습니다. 예약 Tweet의 경우 Tweet의 scheduled_at 시간 전까지 편집할 수 있습니다. 초안 Tweet은 무기한 편집할 수 있습니다. 그러나 한 번 게시된 이후에는 Tweet을 널캐스트에서 오가닉으로, 또는 그 반대로 변경할 수 없습니다.

​

Tweet 프로모션

게시되었거나 예약된 Tweet만 프로모션할 수 있습니다. 이들 Tweet은 널캐스트(nullcast) 형태이거나 오가닉(organic)일 수 있으며, 이에 대한 제한은 없습니다. 광고주는 권한을 얻은 경우 자신이 작성한 Tweet뿐 아니라 다른 사용자의 Tweet도 프로모션할 수 있습니다. (자세한 내용은 다른 사용자의 Tweet 프로모션을 참고하세요.)

여러 개의 Tweet을 단일 캠페인에서 프로모션할 수 있습니다. 마찬가지로, 하나의 Tweet을 하나 이상의 캠페인에서 프로모션할 수 있습니다.

게시된 Tweet을 프로모션하려면 POST accounts/:account_id/promoted_tweets endpoint를 사용하세요. 이 엔드포인트는 게시된 Tweet을 라인 아이템에 연결합니다. 예약된 Tweet을 프로모션하려면 POST accounts/:account_id/scheduled_promoted_tweets endpoint를 사용하세요.

​

Tweet ID

게시된, 예약된, 초안 Tweet의 ID는 숫자형이면서 64비트 부호 없는 정수입니다. 예를 들어, 다음에 나오는 게시된 Tweet의 ID는 1166476031668015104입니다.

게시되었거나 예약된 Tweet이 프로모션되면, 이에 해당하는 promoted Tweet 엔터티가 생성됩니다. 이 엔터티들은 각각 고유한 ID를 가지며, 영문자와 숫자가 혼합된(alphanumeric) 형식이고 base-36으로 인코딩된 값으로 표현됩니다. 예를 들어, 위의 게시된 Tweet을 프로모션하여 line item 6c62d와 연결하면 다음과 같은 API 응답이 반환됩니다.

$ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104"
{
  "request": {
    "params": {
      "tweet_ids": [
        1166476031668015104
      ],
      "line_item_id": "6c62d",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "line_item_id": "6c62d",
      "id": "3qwlq6",
      "entity_status": "ACTIVE",
      "created_at": "2019-09-12T21:39:10Z",
      "updated_at": "2019-09-12T21:39:10Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "1166476031668015104",
      "deleted": false
    }
  ],
  "total_count": 1
}

create 요청에 함께 전달된 Tweet ID와 line item ID 외에도, 응답에는 값이 3qw1q6인 id 필드가 포함되며, 이는 프로모션된 Tweet ID입니다.

​

캐러셀

​

소개

X Ads API는 비디오 캐러셀과 이미지 캐러셀을 생성하고 조회하는 기능을 지원합니다. 캐러셀은 2개에서 6개 사이의 미디어 자산을 포함할 수 있는 카드 타입입니다. 캐러셀 카드는 사용자를 웹사이트로 이동시키거나 모바일 앱 설치를 유도할 수 있습니다. 캐러셀의 개요, 장점, 모범 사례, FAQ에 대한 자세한 내용은 X의 Carousel Ads 페이지를 참고하세요.

캐러셀은 다른 카드 타입과 마찬가지로 Tweet에 사용할 수 있으며, 이렇게 만든 Tweet은 프로모션할 수 있습니다. 전체 워크플로우는 이미 익숙한 것과 동일합니다:

1. 미디어 업로드
2. 카드 생성
3. Tweet 생성
4. Tweet 프로모션

유일한 차이점은 카드 생성 방식입니다. 다른 카드 생성 요청은 쿼리 매개변수를 허용하는 반면, 캐러셀 카드 생성 요청은 JSON POST 본문만 허용합니다.

​

엔드포인트

Ads API는 캐러셀의 생성과 조회를 지원합니다.

어떤 종류의 캐러셀이든 생성하려면 POST accounts/:account_id/cards 엔드포인트를 사용하세요. 캐러셀을 조회하려면 GET accounts/:account_id/cards 엔드포인트를 사용하세요.

​

JSON POST Body

캐러셀은 두 개의 컴포넌트를 사용해 생성됩니다. 첫 번째는 사용할 미디어 에셋을 지정하고, 두 번째는 웹사이트 또는 App에 대한 정보를 지정합니다.

구체적으로, 캐러셀 카드는 다음과 같은 컴포넌트를 이 순서로 사용해 생성합니다:

• SWIPEABLE_MEDIA 컴포넌트 1개 — 미디어 키 배열을 입력으로 받습니다.
• 아래 중 하나:
• 웹사이트 정보를 지정하는 DETAILS 컴포넌트
• App 정보를 지정하는 BUTTON 컴포넌트

SWIPEABLE_MEDIA 컴포넌트에는 2개에서 6개 사이의 이미지 또는 동영상을 지정할 수 있는 media_keys 배열이 반드시 포함되어야 합니다. 미디어 키를 전달하는 순서에 따라 렌더링 순서가 결정됩니다.

{
  "type": "SWIPEABLE_MEDIA",
  "media_keys": [
    "13_1089771253848666112",
    "13_1191948012077092867"
  ]
}

다시 한 번 상기하자면, GET accounts/:account_id/media_library 엔드포인트에 요청을 보내 미디어 키를 얻을 수 있습니다.

두 번째 컴포넌트 객체의 구성은 사용자를 웹사이트로 이동시키고 싶은지, 아니면 앱 설치를 유도하고 싶은지에 따라 달라집니다. 아래 표는 이 두 가지 옵션을 요약한 것입니다. (참고: 나열된 모든 키는 필수입니다.)

	웹사이트	앱
컴포넌트 type 지정	"type": "DETAILS"	"type": "BUTTON"
제목/레이블	"title": "X"	"label": { "type": "ENUM", "value": "INSTALL" }
목적지	"destination": { "type": "WEBSITE", "url": "https://www.x.com" }	"destination": { "type": "APP", ... }

이를 모두 조합하면, 웹사이트 캐러셀에 대한 예시 JSON POST 본문은 아래와 같습니다.

{
  "name": "website carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "DETAILS",
      "title": "X",
      "destination": {
        "type": "WEBSITE",
        "url": "https://www.x.com"
      }
    }
  ]
}

BUTTON 컴포넌트 내 App 목적지 객체에는 국가 코드와 하나 이상의 앱 식별자가 필요합니다. 선택적으로 딥 링크를 포함할 수 있습니다. 이러한 필드에 대한 설명은 reference documentation을 참조하세요.

이를 종합하면, 아래는 App 캐러셀 JSON POST 요청 본문의 예시입니다.

{
  "name": "app carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "iphone_app_id": "333903271"
      }
    }
  ]
}

​

예시

이 섹션에서는 동영상 웹사이트 캐러셀 카드를 생성하는 방법과 이를 Tweet에서 사용하는 방법을 보여줍니다. 위에서 언급했듯이 워크플로우는 이미 익숙한 것과 동일합니다. 미디어를 업로드하고, 카드를 생성하고, Tweet을 생성하면 됩니다. 유일한 차이점은 카드를 생성하는 방식입니다.

미디어

먼저, 새 미디어 에셋을 업로드하거나 기존 에셋을 사용할 수 있습니다. 새 미디어 에셋을 업로드하고 Media Library에 추가하는 방법에 대한 자세한 내용은 Media Library Guide를 참고하세요.

미디어 에셋이 Media Library에 저장되면 GET accounts/:account_id/media_library 엔드포인트를 사용하여 가져옵니다. media_type 요청 파라미터를 사용해 결과를 특정 미디어 유형으로 한정합니다.

$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_type": "VIDEO"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "tweeted": true,
      "duration": 5283,
      "name": "Sunrise",
      "file_name": "sunrise.mp4",
      "description": null,
      "media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9",
      "poster_media_key": "3_1089771253848666112",
      "media_key": "13_1089771253848666112",
      "created_at": "2019-01-28T06:24:48Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg",
      "title": null,
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2019-08-23T19:05:33Z",
      "deleted": false
    },
    {
      "tweeted": true,
      "duration": 15248,
      "name": "snow",
      "file_name": "snow.mp4",
      "description": "Two, three, and to the four",
      "media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13",
      "poster_media_key": "3_1191948012077092867",
      "media_key": "13_1191948012077092867",
      "created_at": "2019-11-06T05:18:46Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg",
      "title": "One",
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2020-03-27T22:23:18Z",
      "deleted": false
    }
  ]
}

캐러셀 생성

캐러셀을 생성하려면 POST accounts/:account_id/cards 엔드포인트를 사용하세요. 이전 요청에서 반환된 media key들을 사용합니다. media key들이 전달되는 순서에 따라 렌더링되는 순서가 결정된다는 점을 기억하세요.

$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "X","destination":{"type":"WEBSITE", "url":"https://www.x.com"}}]}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "website carousel",
    "components": [
      {
        "type": "SWIPEABLE_MEDIA",
        "media_keys": [
          "13_1089771253848666112",
          "13_1191948012077092867"
        ]
      },
      {
        "type": "DETAILS",
        "title": "X",
        "destination": {
          "type": "WEBSITE",
          "url": "https://www.x.com/",
          "tco_url": "https://t.co/dyTMHWKWZb"
        }
      }
    ],
    "id": "ars7m",
    "created_at": "2020-11-11T07:51:47Z",
    "card_uri": "card://1326432421105995776",
    "updated_at": "2020-11-11T07:51:47Z",
    "deleted": false,
    "card_type": "UNIFIED"
  }
}

다른 카드와 마찬가지로 캐러셀 카드의 응답에는 Tweet을 생성할 때 사용할 card_uri가 포함되어 있습니다.

Tweet

POST accounts/:account_id/tweet 엔드포인트를 사용하여 Tweet을 생성합니다. 이전 요청에서 반환된 card_uri를 사용하세요. (가독성을 위해 응답 일부가 생략되었습니다.)

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792"

{
  "data": {
    "created_at": "Wed Nov 11 07:58:27 +0000 2020",
    "id": 1326434098324385792,
    "id_str": "1326434098324385792",
    "text": "Swipe",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "Ads API Internal Test App",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691300,
      "id_str": "756201191646691328",
      ...
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": [
      2417045708
    ],
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "Swipe",
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}

Tweet 미리보기

GET accounts/:account_id/tweet_previews 엔드포인트를 사용해 Tweet을 확인할 수 있습니다.

​

크리에이티브 메타데이터 태그 지정

​

소개

이 가이드는 크리에이티브 파트너, 에이전시 및 크리에이티브 개발자가 X 캠페인에서 사용되는 에셋에 태그를 추가해 개별 에셋의 가치와 성과를 더 잘 파악할 수 있도록 돕기 위한 것입니다.

참고: 미디어 에셋은 해당 미디어 에셋을 생성한 파트너 또는 개발자만 태그해야 합니다. 미디어 에셋의 사용자가 해당 미디어 에셋을 생성하지 않았다면 메타데이터 태깅을 구현하지 마십시오.

Creative Metadata Tagging은 에셋이 X 내 어디에 업로드되든, 에셋을 업로드하는 주체가 누구이든 상관없이 크리에이티브 파트너가 제작한 이미지와 동영상에 대한 제작자 정보를 제공하는 기능입니다. 크리에이티브 에셋과 크리에이티브 파트너 간의 연결을 만들기 위해 XMP 표준이 사용됩니다.

​

크리에이티브 에셋 태깅

다음 표는 각 이미지 관련 리소스의 응답에서 현재 사용 가능한 식별자 유형과 해당 속성 이름을 보여줍니다. 크리에이티브 에셋에 태그를 지정하려면 태깅 도구가 필요합니다. ExifTool은 메타 정보를 읽고, 쓰고, 편집하기 위한 플랫폼 독립적인 Perl 라이브러리와 명령줄 애플리케이션으로 구성되어 있으며, 사용을 권장합니다. 지원되는 모든 파일 유형을 확인하세요.

제공된 ExifTool 설치 안내를 따라 설치하세요. macOS와 Linux에서 exiftool 설치 명령을 제공하여 설치를 더욱 간단하게 해 주는 Homebrew 소프트웨어 패키지도 있습니다. 명령줄에서 exiftool -ver를 입력하여 도구의 버전 번호가 반환되는지 확인함으로써 도구가 올바르게 설치되었는지 검증할 수 있습니다. ExifTool 명령 파라미터에 대한 자세한 내용은 ExifTool 문서를 참고하세요.

크리에이티브 파트너는 새 크리에이티브 에셋이나 기존 크리에이티브 에셋에 대해 X app_id를 contributor XMP 태그와 date 태그의 메타데이터 값으로 지정할 수 있습니다. 크리에이티브 에셋은 미디어 업로드 시 기존 크기 제한을 따르게 됩니다. 

참고: X에서 contributor XMP 태그를 사용하는 것은 메타데이터가 X에서 진행되는 캠페인에 대한 값만을 캡처하도록 보장하기 위한 것입니다.

exiftool -contributor="<YOUR APP ID>" -creative_file.jpg

exiftool -date="<date>" -creative_file.jpg

app_id는 개발자 콘솔의 Projects & Apps 아래에서 찾을 수 있습니다. 예: 16489123

다음 예시는 이미지에 대해 app_id를 contributor 태그로, date를 date 태그로 추가하는 방법을 보여줍니다:

app_id:858382169

date:2022-03-13

creative_file: eiffel_tower.jpg

exiftool -contributor=858382169 eiffel_tower.jpg

   1 image files updated

exiftool -date=2022-03-13 eiffel_tower.jpg

  1 image files updated

이미지에 태그가 올바르게 적용되었는지 확인하세요: 

exiftool -xmp:all -G1 <filename>

예시:

exiftool -xmp:all -G1 eiffel_tower.jpg

[XMP]        XMP Toolkit            : Image::ExifTool 12.30

[XMP]        Contributor            : 858382169

[XMP]        Date                   : 2022:03:13

​

질문이 있으신가요?

태깅과 어트리뷰션이 올바르게 설정되었는지 확인하려면, 태깅이 적용된 샘플 에셋을 [e-mail]으로 보내 주시면 X 담당자가 검토해 드립니다.

​

API 참조 문서

​

계정 미디어

Postman에서 실행

​

GET accounts/:account_id/account_media

현재 계정에 연결된 일부 또는 전체 계정 미디어의 세부 정보를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/account_media

​

매개변수

Name	Description
account_id required	활용할 계정에 대한 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 타입: string 예시: 18ce54d4x5t
account_media_ids optional	쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 계정 미디어로만 한정합니다. 최대 200개의 ID를 제공할 수 있습니다. 타입: string 예시: 3wpx
count optional	각 개별 요청에서 가져오려는 레코드 수를 지정합니다. 타입: int 기본값: 200 최소, 최대: 1, 1000
creative_types optional	지정된 크리에이티브 타입과 일치하는 계정 미디어로만 응답을 한정합니다. 여러 크리에이티브 타입은 enum 값을 쉼표로 구분하여 지정할 수 있습니다. 타입: enum 가능한 값: BANNER, BANNER_TABLET, INTERSTITIAL, INTERSTITIAL_LANDSCAPE, INTERSTITIAL_LANDSCAPE_TABLET, INTERSTITIAL_TABLET, MEDIUM_RECTANGLE, PREROLL, VAST_PREROLL
cursor optional	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참고하세요. 타입: string 예시: 8x7v00oow
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참고하세요. 타입: string 예시: created_at-asc
with_deleted optional	삭제된 결과를 요청에 포함합니다. 타입: boolean 기본값: false 가능한 값: true, false
with_total_count optional	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

​

예시 응답

{
  "request": {
    "params": {
      "account_media_ids": [
        "3wpx"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_id": "13_771791717175468032",
      "media_url": null,
      "creative_type": "PREROLL",
      "id": "3wpx",
      "created_at": "2016-09-02T19:27:52Z",
      "updated_at": "2016-09-02T19:27:52Z",
      "deleted": false
    }
  ]
}

현재 계정에 연결된 특정 계정 미디어 객체를 가져옵니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id

​

매개변수

Name	Description
account_id 필수	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
account_media_id 필수	이 요청에서 작업 대상으로 사용하는 계정 미디어에 대한 참조입니다. Type: string Example: 2pnfd
with_deleted 선택	요청 결과에 삭제된 항목을 포함할지 여부입니다. Type: boolean Default: false Possible values: true, false

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd

​

응답 예시

{
  "request": {
    "params": {
      "account_media_id": "2pnfd",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-07-28T01:44:41Z",
    "deleted": false
  }
}

현재 계정의 지정된 계정 미디어 객체를 삭제합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id

​

Parameters

Name	Description
account_id required	레버리지 계정에 대한 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 형식: string 예시: 18ce54d4x5t
account_media_id required	요청에서 사용하려는 account media를 지정합니다. 형식: string 예시: 2pnfd

​

요청 예제

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd

​

응답 예시

{
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-08-25T17:16:26Z",
    "deleted": true
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "account_media_id": "2pnfd"
    }
  }
}

​

카드

Postman에서 실행

참고: 카드를 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

​

매개변수

Name	Description
account_id required	레버리지드 계정의 식별자입니다. 리소스 경로 내에 표시되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_types optional	쉼표로 구분된 enum 값 목록을 지정하여, 응답을 원하는 카드 유형으로만 한정합니다. Type: enum Possible values: 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 optional	쉼표로 구분된 식별자 목록을 지정하여, 응답을 원하는 카드로만 한정합니다. 최대 200개의 카드 id를 제공할 수 있습니다. Type: string Example: 1044294149527166979,1044301099031658496
card_uris optional	쉼표로 구분된 식별자 목록을 지정하여, 응답을 원하는 카드로만 한정합니다. 최대 200개의 카드 URI 값을 제공할 수 있습니다. Type: string Example: card://1044294149527166979,card://1044301099031658496
count optional	요청 한 번당 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 100 Min, Max: 1, 200
cursor optional	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
include_legacy_cards optional	응답에 레거시 웹사이트 및 App 카드를 포함합니다. 레거시 카드는 리소스 URL 형식이 다음과 같은 카드입니다: accounts/:account_id/cards/:card_type. 자세한 내용은 이 개발자 포럼 게시물을 참조하세요. Type: boolean Default: false Possible values: true, false
q optional	name으로 카드를 한정하기 위한 선택적 쿼리입니다. 모든 카드를 가져오려면 이 매개변수를 생략하세요. 최대 길이: 80자. 참고: 대소문자를 구분하지 않는 접두사 일치(prefix matching)를 수행합니다. Type: string Example: dtc
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: created_at-asc
with_deleted optional	요청에 삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1

​

응답 예시

{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8wzvldqtc",
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

현재 계정에 연결된 한 개의 카드에 대한 상세 정보를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/:card_id

​

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_id required	카드 id입니다. Type: string Example: 1044294149527166979
with_deleted optional	요청에 삭제된 결과를 포함할지 여부를 지정합니다. Type: boolean Default: false Possible values: true, false

​

예제 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

​

POST accounts/:account_id/cards

지정된 계정에 연관된 새 카드를 생성합니다.

카드 생성 요청에서는 JSON 형식의 POST 본문만 허용됩니다. Content-Type은 application/json으로 설정해야 합니다.

자세한 사용 예시는 Carousels 가이드를 참고하세요.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards

​

매개변수

JSON POST 요청 본문에는 카드의 name과 components 배열이 반드시 포함되어야 합니다. 각 component는 객체로 표현되며, 카드에서 광고주가 보게 되는 속성을 정의합니다.

다음 예시는 페이로드의 전반적인 구조를 보여 주지만, 실제로 동작하는 정보는 아닙니다.

{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

컴포넌트에 대한 추가 정보는 아래를 참고하세요.

Name	Description
account_id required	사용할 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
name required	카드의 이름입니다. 최대 길이: 80자. Type: string Example: component based card
components sometimes required	카드를 생성하는 데 사용할 컴포넌트를 설명합니다. 아래에 추가 정보가 있습니다. slides와 함께 지정할 수 없습니다. 참고: 컴포넌트의 순서는 중요합니다. Type: array of objects
slides sometimes required	이 배열의 배열을 사용하여 Multi-Destination Carousel을 생성합니다. 각 카드를 컴포넌트의 그룹으로서 설명합니다. 각 슬라이드는 하나의 카드를 완전하게 표현해야 합니다. components와 함께 지정할 수 없습니다. 참고: 각 슬라이드의 순서는 중요합니다. Type: array of array

​

구성 요소

모든 구성 요소에는 객체의 스키마를 결정하는 type 필드가 포함되어야 합니다. Ads API는 미디어 기반 구성 요소와 설명 기반 구성 요소로 구분된 다음 구성 요소 type을 지원합니다.

• 미디어:
• MEDIA: 단일 비디오 또는 이미지
• SWIPEABLE_MEDIA: 2~6개의 비디오 또는 이미지
• 설명:
• DETAILS
• BUTTON

각 구성 요소에는 (type 키 외에) 필수 필드 집합이 있습니다. 이는 다음 표에 나와 있습니다.

구성 요소 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 키는 의도적으로 생략되어 있습니다). (줄임표는 더 많은 정보를 지정해야 하는 위치를 나타냅니다.)

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        ...
      },
      "destination": {
        ...
      }
    }
  ]
}

구성 요소 객체가 지정되는 순서는 카드가 렌더링될 때 위에서 아래로 표시되는 순서를 결정합니다. 카드는 하나의 미디어 기반 구성 요소와 DETAILS 또는 BUTTON 구성 요소 중 하나를 사용해 생성해야 합니다. 설명 기반 구성 요소는 미디어 아래에 렌더링되며, URL이나 모바일 App 등의 목적지와 연결됩니다.

Label

Label은 버튼에 표시되는 텍스트를 정의하므로 BUTTON 구성 요소에만 적용됩니다. Label 객체에는 필수 키인 type과 value가 있습니다. type은 ENUM으로 설정해야 하고, value는 BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY, SHOP 중 하나여야 합니다.

이전 예제를 기반으로 아래는 BUTTON 구성 요소 안에 있는 label 객체의 예시입니다.

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        ...
      }
    }
  ]
}

목적지(Destination)

목적지는 광고주가 사용자를 이동시키려는 위치를 의미합니다. 목적지는 항상 DETAILS 또는 BUTTON 컴포넌트 안에 포함되어야 합니다. 목적지 type에는 WEBSITE과 APP 두 가지가 있습니다.

참고: 웹사이트 목적지는 DETAILS 컴포넌트에서만 사용할 수 있고, 앱 목적지는 BUTTON 컴포넌트에서만 사용할 수 있습니다.

웹사이트 목적지(Website Destination)

Name	Description
type required	목적지의 type으로, 이 값에 따라 스키마가 결정됩니다. Type: enum 가능한 값: WEBSITE
url required	사용자를 리디렉션할 웹사이트의 URL입니다. Type: string 예시: https://devcommunity.x.com/c/advertiser-api

앱 목적지(App Destination)

Name	Description
type required	목적지의 type으로, 이 값에 따라 스키마가 결정됩니다. Type: enum 가능한 값: APP
country_code required	앱이 판매되는 국가에 대한 ISO 3166-1 alpha-2 두 글자 코드입니다. Type: string 예시: US
googleplay_app_id sometimes required	Google Play 애플리케이션 패키지 이름입니다. 참고: 다음 필드 중 최소 하나는 필수입니다: ios_app_store_identifier 또는 googleplay_app_id. Type: string 예시: com.twitter.android
ios_app_store_identifier sometimes required	iOS App Store 식별자입니다. 참고: 다음 필드 중 최소 하나는 필수입니다: ios_app_store_identifier 또는 googleplay_app_id. Type: string 예시: 333903271
googleplay_deep_link optional	홍보 중인 Android 앱으로 연결되는 딥 링크입니다. 참고: googleplay_app_id가 제공된 경우에만 사용할 수 있습니다. Type: string
ios_deep_link optional	홍보 중인 iOS 앱으로 연결되는 딥 링크입니다. 참고: ios_app_store_identifier가 제공된 경우에만 사용할 수 있습니다. Type: string

​

요청 예시

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "components create cards",
    "components": [
      {
        "type": "MEDIA",
        "media_key": "3_1323490622599176192"
      },
      {
        "type": "BUTTON",
        "label": {
          "type": "ENUM",
          "value": "INSTALL"
        },
        "destination": {
          "type": "APP",
          "country_code": "US",
          "googleplay_app_id": "com.twitter.android"
        }
      }
    ],
    "created_at": "2020-11-11T05:42:25Z",
    "card_uri": "card://1326399865065238531",
    "id": "1321554298900107264",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false,
    "card_type": "IMAGE_APP"
  }
}

현재 계정에 연결된 지정된 카드를 업데이트합니다.

카드 수정 요청은 JSON 형식의 POST 본문만 허용합니다. Content-Type은 application/json으로 설정해야 합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264

​

매개변수

JSON POST 본문에는 업데이트할 매개변수가 포함되어야 합니다. 이 요청은 페이로드에 지정된 매개변수로 각 필드를 대체합니다. 컴포넌트는 객체로 표현되며, 카드의 광고주용 속성을 설명합니다.

다음 예시는 페이로드의 전체적인 구조를 보여 주지만, 실제로 동작하지 않는 정보가 포함되어 있습니다.

{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

POST accounts/:account_id/cards의 컴포넌트와 슬라이드에 대한 추가 정보입니다.

Name	Description
account_id required	대상 계정을 식별하는 값입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
name optional	카드의 이름입니다. 최대 길이: 80자. Type: string Example: component based card
components optional	카드를 업데이트하는 데 사용할 컴포넌트를 지정합니다. 아래에 추가 정보가 있습니다. slides와 함께 지정할 수 없습니다. 참고: 컴포넌트의 순서는 중요합니다. Type: array of objects
slides optional	Multi-Destination Carousel(다중 도착지 캐러셀)을 업데이트하기 위해 사용하는 배열의 배열입니다. 각 카드를 컴포넌트 그룹으로 표현합니다. 각 슬라이드는 하나의 카드를 완전하게 표현해야 합니다. components와 함께 지정할 수 없습니다. 참고: 각 슬라이드의 순서는 중요합니다. Type: array of array

​

예시 요청

이 예시에서는 위의 예시에서 name 값을 업데이트하고, components 필드의 media_keys 중 하나를 제거합니다.

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

{
  "name": "changed name",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "3_1075096386931052545"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "OPEN"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
      }
    }
  ]
}

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "changed name",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

현재 계정의 지정된 카드를 삭제합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/:card_id

​

매개변수

Name	Description
account_id 필수	레버리지 계정을 식별하는 값입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
card_id 필수	삭제할 카드의 id입니다. 유형: string 예시: 1044294149527166979

​

예시 요청

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": true,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

​

Cards Fetch

Postman에서 실행

현재 계정에 연결된 여러 카드를 card_uri를 기준으로 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/all

​

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_uris required	쉼표로 구분된 식별자 목록을 지정하여 응답 범위를 원하는 카드로만 한정합니다. 최대 200개의 카드 URI 값을 제공할 수 있습니다. Type: string Example: card://1044294149527166979,card://1044301099031658496
with_deleted optional	요청에 삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496

​

예시 응답

{
  "request": {
    "params": {
      "card_uris": [
        "card://1044294149527166979",
        "card://1044301099031658496"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "name": "X App",
      "googleplay_app_id": "com.twitter.android",
      "image_display_height": "836",
      "country_code": "US",
      "id": "692xn",
      "wide_app_image": "https://pbs.twimg.com/media/Dc263l9VwAAAeEH.jpg",
      "created_at": "2018-09-24T18:35:01Z",
      "image_display_width": "1600",
      "card_uri": "card://1044294149527166979",
      "updated_at": "2018-09-24T18:35:01Z",
      "app_cta": "INSTALL",
      "deleted": false,
      "card_type": "IMAGE_APP_DOWNLOAD"
    },
    {
      "video_poster_height": "9",
      "name": "Developer Platform",
      "website_shortened_url": "https://t.co/zadeUSVD18",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/991374284135137280.vmap",
      "content_duration_seconds": "24",
      "video_owner_id": "756201191646691328",
      "video_content_id": "13_991374284135137280",
      "website_display_url": "developer.x.com",
      "id": "6933h",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/991374284135137280/pl/sQrBsE9mFvNep9Cx.m3u8?tag=2",
      "website_dest_url": "https://developer.x.com",
      "created_at": "2018-09-24T19:02:38Z",
      "card_uri": "card://1044301099031658496",
      "title": "Developer Platform",
      "website_url": "https://developer.x.com",
      "updated_at": "2018-09-24T19:02:38Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/991374284135137280/img/YbbGQHvWRjoFgrLz.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_WEBSITE"
    }
  ]
}

card_id 값을 사용해 현재 계정에 연결된 특정 카드를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id

​

Parameters

Name	Description
account_id 필수	레버리지드 계정(leveraged account)의 식별자입니다. 리소스 경로에 포함되며, 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

​

응답 예시

{
  "request": {
    "params": {
      "card_id": "508pf",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "video website card",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/867520357225418752.vmap",
    "content_duration_seconds": "21",
    "video_owner_id": "756201191646691328",
    "video_content_id": "13_867520357225418752",
    "website_display_url": "developer.x.com",
    "id": "508pf",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/867520357225418752/pl/TPHeH5ZlHFCa2TeJ.m3u8",
    "website_dest_url": "https://developer.x.com/en/docs/ads/creatives/api-reference/video-website#post-accounts-account-id-cards-video-website",
    "created_at": "2017-11-10T09:00:35Z",
    "card_uri": "card://928910245920829440",
    "title": "VWC",
    "website_url": "https://t.co/F81hp59pUF",
    "updated_at": "2018-01-05T05:43:31Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/867520357225418752/img/E3pnXM0sCKnRsFih.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_WEBSITE"
  }
}

​

임시 저장된 Tweet

Postman에서 실행

​

GET accounts/:account_id/draft_tweets

현재 계정에 연결된 일부 또는 모든 Draft Tweet의 상세 정보를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets

​

매개변수

Name	Description
account_id required	레버리지드 계정을 식별하는 값입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
count optional	각 요청마다 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 100 Min, Max: 1, 200
cursor optional	다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참고하세요. Type: string Example: c-jh1g0ryb
user_id optional	Draft Tweets를 조회할 사용자를 지정합니다. 설정하지 않으면 계정의 FULL 프로모터블(promotable) 사용자가 기본값으로 사용됩니다. Type: string Example: 756201191646691328

​

요청 예시

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1

​

예시 응답

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name" null,
      "text": "hello, world",
      "user_id": "756201191646691328",
      "id": "994791681219231744",
      "nullcast": true,
      "created_at": "2018-05-11T04:09:53Z",
      "card_uri": null,
      "updated_at": "2018-05-11T04:09:53Z",
      "media_keys": []
    }
  ],
  "next_cursor": "c-jh1g0ryb"
}

현재 계정에 연결된 특정 Draft Tweet을 가져옵니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

매개변수

Name	Description
account_id required	대상 계정의 식별자입니다. 리소스 경로 내에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
draft_tweet_id required	요청에서 사용 중인 Draft Tweet을 참조합니다. Type: string Example: 994788364334325760

​

요청 예시

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760

​

예시 응답

{
  "request": {
    "params": {
      "draft_tweet_id": "994788364334325760"
    }
  },
  "data": {
    "name": null,
    "text": "#TwitterDev",
    "user_id": "756201191646691328",
    "id": "994788364334325760",
    "nullcast": true,
    "created_at": "2018-05-11T03:56:42Z",
    "card_uri": "card://958225772740714496",
    "updated_at": "2018-05-11T03:56:42Z",
    "media_keys": []
  }
}

​

POST accounts/:account_id/draft_tweets

계정의 전체 프로모션 가능 사용자(기본값) 또는 as_user_id 매개변수로 지정한 사용자에 대한 임시 Tweet을 생성합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets

​

매개변수

Name	Description
account_id required	레버리지 계정(leveraged account)의 식별자입니다. 리소스 경로 내에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
as_user_id required	Tweet을 게시하려는 광고주의 사용자 ID입니다. 광고주는 ads.x.com을 통해 자신의 광고 계정에 대한 액세스 권한을 사용자의 핸들(또는 여러 핸들)에게 부여해야 합니다. 이 권한을 통해 광고주의 핸들이 아니라 사용자의 핸들의 OAuth 토큰을 사용하여 API를 호출할 수 있습니다. Type: string Example: 756201191646691328
text sometimes required	상태 업데이트의 텍스트입니다. media_keys가 지정되지 않은 경우 필수입니다. Type: string Example: Just setting up my X.
card_uri optional	사용 가능한 경우, 카드 응답의 card_uri 값을 사용하여 Tweet에 카드를 연결합니다. Type: string Example: card://960880280705392541
media_keys optional	쉼표로 구분된 식별자 목록을 지정하여 Tweet에 미디어를 연결합니다. 최대 4개의 이미지, 1개의 애니메이티드 GIF 또는 1개의 비디오를 포함할 수 있습니다. 참고: 미디어 에셋은 계정의 Media Library에 있어야 합니다. Type: string Example: 13_1153584529292270722
nullcast optional	nullcast(또는 “Promoted-only”) Tweet을 생성할지 여부입니다. Type: boolean Default: true Possible values: true, false
name optional	Draft Tweet의 이름입니다. 최대 길이: 80자입니다. Type: string Example: Tweet with name

​

예시 요청

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.

​

예시 응답

{
  "request": {
    "params": {
      "text": "Just setting up my X.",
      "as_user_id": "756201191646691328"
    }
  },
  "data": {
    "name": null,
    "text": "Just setting up my X.",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:14:13Z",
    "media_keys": []
  }
}

현재 계정의 지정된 Draft Tweet을 업데이트합니다.

​

리소스 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 선택	사용 가능한 경우, 임의의 cards 응답에서 card_uri 값을 사용하여 Tweet에 카드를 연결합니다. 참고: 값 없이 매개변수만 지정하면 설정이 해제(제거)됩니다. 타입: string 예시: card://970582057284129151
media_keys 선택	쉼표로 구분된 식별자 목록을 지정하여 Tweet에 미디어를 연결합니다. 최대 4개의 이미지, 1개의 애니메이티드 GIF 또는 1개의 비디오를 포함할 수 있습니다. 참고: 미디어 자산은 계정의 Media Library에 있어야 합니다. 참고: 값 없이 매개변수만 지정하면 설정이 해제(제거)됩니다. 타입: string 예시: 13_1153584529292270722
nullcast 선택	nullcast(또는 “Promoted-only”)된 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

​

예시 응답

{
  "request": {
    "params": {
      "draft_tweet_id": 994747471329873920,
      "text": "just setting up my twttr"
    }
  },
  "data": {
    "name": null,
    "text": "just setting up my twttr",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:16:59Z",
    "media_keys": []
  }
}

현재 계정의 지정된 Draft Tweet을 영구적으로 삭제합니다.

참고: 해당 Draft의 메타데이터를 사용해 Tweet 또는 Scheduled Tweet을 생성한 후에는 Draft를 삭제할 것을 강력히 권장합니다.

참고: 이 작업은 완전 삭제(hard delete)입니다. 따라서 삭제된 Draft Tweet은 다시 복구할 수 없습니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

매개변수

Name	Description
account_id required	레버리지 계정(leveraged account)의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
draft_tweet_id required	이 요청으로 처리하려는 Draft Tweet을 가리키는 참조입니다. Type: string Example: 994787835663155200

​

요청 예시

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200

​

예시 응답

{
  "request": {
    "params": {
      "draft_tweet_id": "994787835663155200"
    }
  },
  "data": {
    "name": null,
    "text": "hello, world",
    "user_id": "756201191646691328",
    "id": "994787835663155200",
    "nullcast": true,
    "status": "DELETED",
    "created_at": "2018-05-11T03:54:36Z",
    "card_uri": null,
    "updated_at": "2018-05-11T04:07:31Z",
    "media_keys": []
  }
}

​

POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id

모바일 기기에서 Draft Tweet을 미리 봅니다.

요청이 성공하면 인증된 사용자가 로그인해 있는 모든 기기로 알림이 전송됩니다. 알림을 클릭하면 사용자가 Draft Tweet을 보고 상호작용할 수 있는 타임라인이 열리며, 이를 통해 자동 재생, 볼륨, 전체 화면, 동영상 웹사이트 카드 도킹 등과 같은 동작을 테스트할 수 있습니다.

참고: 기기에서의 미리보기는 알림을 받은 사용자에게만 표시됩니다.

참고: 알림은 X 공식 앱에만 전송됩니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id

​

매개변수

이름	설명
account_id required	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 타입: string 예시: 18ce54d4x5t
draft_tweet_id required	요청에서 조작하려는 Draft Tweet에 대한 참조입니다. 타입: string 예시: 996132315829948416

​

예시 요청

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "draft_tweet_id": "996132315829948416"
    }
  },
  "message": "See @apimctestface's notifications in the X app to preview your Tweet."
}

​

이미지 대화 카드

Postman에서 실행

참고: 카드를 Tweet에 연결하려면 card_uri 파라미터를 POST accounts/:account_id/tweet, POST statuses/update, 또는 POST accounts/:account_id/scheduled_tweets 엔드포인트 중 하나와 함께 사용하세요.

​

GET accounts/:account_id/cards/image_conversation

현재 계정에 연결된 일부 또는 모든 이미지 대화 카드의 세부 정보를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation

​

Parameters

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_ids optional	쉼표로 구분된 ID 목록을 지정하여 응답을 원하는 이미지 대화 카드로만 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: 59woh
count optional	각 요청마다 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
q optional	name으로 카드를 범위 지정하기 위한 선택적 쿼리입니다. 모두 가져오려면 이 매개변수를 생략합니다. 최대 길이: 80자. Note: 대소문자를 구분하지 않는 접두어(prefix) 매칭을 수행합니다. Type: string Example: night
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: created_at-asc
with_deleted optional	요청에 삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count 응답 속성을 포함합니다. Note: 이 매개변수와 cursor는 상호 배타적입니다. Note: total_count를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200건으로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

​

예제 요청

GET https://ads-api.x.com/12/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"
    }
  ]
}

현재 계정에 연결된 특정 이미지 대화 카드를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

매개변수

이름	설명
account_id 필수	레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_id 필수	요청에서 사용 중인 이미지 대화 카드(image conversation card)를 가리키는 참조값입니다. Type: string Example: 59woh
with_deleted 선택	요청 결과에 삭제된 항목을 포함할지 여부입니다. Type: boolean Default: false 가능한 값: true, false

​

요청 예시

GET https://ads-api.x.com/12/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

지정된 계정에 연결된 새 이미지 대화 카드(image conversation card)를 생성합니다.

엔드포인트에 이미지를 업로드하는 방법에 대한 유용한 정보는 Uploading Media를 참고하세요.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation

​

매개변수

Name	Description
account_id required	활용 계정(leveraged account)의 식별자입니다. 리소스 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
first_cta required	첫 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 길이에 포함되지 않음). Type: string Example: #ShareNow
first_cta_tweet required	첫 번째 CTA를 클릭했을 때 사용될 Tweet 텍스트입니다. Type: string Example: I Heart @AdsAPI
media_key required	이 카드에서 사용할 이미지의 media key입니다. Note: 이미지는 계정의 Media Library에 있어야 합니다. Note: 최소 이미지 가로 폭은 800px이어야 하며, 가로:세로 비율은 1.91:1이어야 합니다. Type: string Example: 3_1151345051104991073
name required	카드의 이름입니다. Type: string Example: image conversation card
thank_you_text required	CTA를 클릭한 후 표시될 텍스트입니다. 최대 길이: 23자. Type: string Example: Thank you
second_cta sometimes required	두 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 길이에 포함되지 않음). Type: string Note: title이 설정되지 않은 경우 필수입니다. Example: #ShareAgain
second_cta_tweet sometimes required	두 번째 CTA를 클릭했을 때 사용될 Tweet 텍스트입니다. Note: second_cta가 설정된 경우 필수입니다. Type: string Example: I Heart @AdsAPI Again
title sometimes required	이미지 아래, CTA 위에 표시되는 카드의 제목입니다. 최대 길이: 23자. Type: string Note: second_cta가 설정되지 않은 경우 필수입니다. Example: Start a conversation
third_cta optional	세 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 길이에 포함되지 않음). Type: string Example: #ShareMore
third_cta_tweet sometimes required	세 번째 CTA를 클릭했을 때 사용될 Tweet 텍스트입니다. Type: string Note: third_cta가 설정된 경우 필수입니다. Example: I Heart @TwitterDev
fourth_cta optional	네 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 길기에 포함되지 않음). Type: string Example: #ShareExtra
fourth_cta_tweet sometimes required	네 번째 CTA를 클릭했을 때 사용될 Tweet 텍스트입니다. Type: string Note: fourth_cta가 설정된 경우 필수입니다. Example: I Heart @TwitterDev Again
unlocked_image_media_key optional	instant unlock(즉시 잠금 해제) 시나리오에서 사용될 이미지의 media_key입니다. 쓰기 전용 필드입니다. 응답에서 API는 이 이미지에 대한 X URL을 제공합니다. Note: 이미지는 계정의 Media Library에 있어야 합니다. Note: 최소 이미지 가로 폭은 800px이어야 하며, 가로:세로 비율은 5:2이어야 합니다. Type: string Example: 3_883112887618682880
thank_you_url optional	감사 텍스트와 함께 표시될 URL입니다. Type: string Example: 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

​

응답 예시

{
  "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"
    }
  }
}

현재 계정의 지정된 이미지 대화 카드를 업데이트합니다.

엔드포인트로 이미지를 업로드하는 방법에 대한 유용한 정보는 미디어 업로드하기를 참고하세요.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parameters

Name	Description
account_id required	레버리지 계정에 대한 식별자입니다. 리소스의 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_id required	요청에서 사용 중인 이미지 대화 카드(image conversation card)에 대한 참조입니다. Type: string Example: 4i0qg
first_cta optional	첫 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 포함하지 않음). Type: string Example: #ShareNow
first_cta_tweet optional	첫 번째 CTA가 클릭되었을 때 사용할 Tweet 텍스트입니다. Type: string Example: I Heart @AdsAPI
second_cta optional	두 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 포함하지 않음). Type: string Note: title이 설정되어 있지 않은 경우 필수입니다. Example: #ShareAgain
second_cta_tweet optional	두 번째 CTA가 클릭되었을 때 사용할 Tweet 텍스트입니다. Note: second_cta가 설정된 경우 필수입니다. Type: string Example: I Heart @AdsAPI Again
third_cta optional	세 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 포함하지 않음). Type: string Example: #ShareMore
third_cta_tweet optional	세 번째 CTA가 클릭되었을 때 사용할 Tweet 텍스트입니다. Type: string Note: third_cta가 설정된 경우 필수입니다. Example: I Heart @TwitterDev
fourth_cta optional	네 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 포함하지 않음). Type: string Example: #ShareExtra
fourth_cta_tweet optional	네 번째 CTA가 클릭되었을 때 사용할 Tweet 텍스트입니다. Type: string Note: fourth_cta가 설정된 경우 필수입니다. Example: I Heart @TwitterDev Again
media_key optional	이 카드에서 사용할 이미지의 media key입니다. Note: 이미지는 계정의 Media Library에 있어야 합니다. Note: 최소 이미지 너비는 800px이어야 하며, 가로:세로 비율은 1.91:1이어야 합니다. Type: string Example: 3_1151345051104991073
name optional	카드의 이름입니다. Type: string Example: moon card
thank_you_text optional	CTA가 클릭된 후 표시될 텍스트입니다. 최대 길이: 23자. Type: string Example: Thank you
thank_you_url optional	감사 텍스트와 함께 표시될 URL입니다. Type: string Example: https://example.com/thankyou
title optional	카드의 제목으로, 이미지 아래이자 CTA 위에 표시됩니다. 최대 길이: 23자. Type: string Note: second_cta가 설정되어 있지 않은 경우 필수입니다. Example: Start a conversation
unlocked_image_media_key optional	instant unlock 시나리오에서 사용할 이미지의 media_key입니다. 쓰기 전용 필드입니다. 응답에서 API는 이 이미지에 대한 X URL을 제공합니다. Note: 이미지는 계정의 미디어 라이브러리에 있어야 합니다. Note: 최소 이미지 너비는 800px이어야 하며, 가로:세로 비율은 5:2이어야 합니다. Type: string Example: 3_883112887618682880

​

요청 예시

PUT https://ads-api.x.com/12/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"
    }
  }
}

현재 계정에 속한 지정된 이미지 대화 카드(image conversation card)를 영구적으로 삭제합니다.

참고: 이 작업은 완전 삭제(hard delete)입니다. 따라서 삭제된 카드는 복구할 수 없습니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_id required	요청에서 사용 중인 image conversation card에 대한 참조입니다. Type: string Example: 4i0qe

​

예시 요청

DELETE https://ads-api.x.com/12/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"
    }
  }
}

​

미디어 라이브러리

Postman에서 실행

​

GET accounts/:account_id/media_library

현재 계정과 연결된 일부 또는 전체 미디어 라이브러리 객체의 세부 정보를 가져옵니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/media_library

​

매개변수

Name	Description
account_id required	활용 계정을 식별하는 값입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
count optional	요청당 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 20 Min, Max: 1, 50
cursor optional	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: c-1
media_type optional	응답을 원하는 미디어 type으로만 제한합니다. Type: enum Possible values: GIF, IMAGE, VIDEO
q optional	name, title, file_name, description 필드를 기준으로 리소스 범위를 한정하기 위한 선택적 쿼리입니다. Note: 대소문자를 구분하지 않는 term 매칭을 수행합니다. Type: string Min, Max length: 1, 255

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "count": 1
    }
  },
  "data": [
    {
      "tweeted": true,
      "name": null,
      "file_name": "coffee https://t.co/4tcPU9XUon",
      "media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
      "media_category": "TWEET_IMAGE",
      "media_key": "3_908573900237180928",
      "created_at": "2017-09-15T06:11:12Z",
      "media_status": "TRANSCODE_COMPLETED",
      "media_type": "IMAGE",
      "updated_at": "2017-11-16T06:00:01Z",
      "deleted": false
    }
  ],
  "next_cursor": "c-1"
}

현재 계정에 연결된 특정 미디어 라이브러리 객체를 가져옵니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

매개변수

Name	Description
account_id required	leveraged 계정에 대한 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연동되어 있어야 합니다. Type: string Example: 18ce54d4x5t
media_key required	요청에서 사용 중인 미디어 라이브러리 객체에 대한 참조입니다. Type: string Example: 13_909110614026444802

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802

​

예시 응답

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "13_909110614026444802"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 39973,
    "name": null,
    "file_name": "buildings https://t.co/xFdzrHM5QG",
    "description": null,
    "media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
    "media_category": "AMPLIFY_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
    "poster_media_key": "3_909110614026444802",
    "media_key": "13_909110614026444802",
    "created_at": "2017-09-16T17:43:55Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "buildings",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-09-27T13:04:00Z",
    "deleted": false
  }
}

현재 계정에 미디어 객체를 연결합니다. 자세한 내용은 Media Library 가이드를 참고하세요.

참고: Media Library에 AMPLIFY_VIDEO 미디어 카테고리의 동영상을 추가하면 자동으로 PREROLL account_media 에셋으로 사용할 수 있습니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/media_library

​

매개변수

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스 경로 내에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
media_key required	업로드된 콘텐츠에 대한 media_key입니다. media_category가 지정된 경우 POST media/upload 응답에서 media_key가 반환됩니다. Type: string Example: 3_931236738554519552
description optional	Tweet에 게시될 때 동영상 아래에 표시되는 설명입니다. 최대 길이: 200자입니다. 기본적으로 Tweet에 표시되지 않습니다. 동영상의 description을 표시하려면 POST accounts/:account_id/tweet 엔드포인트에서 video_description 매개변수를 사용하십시오. 참고: 동영상에만 사용할 수 있습니다. Type: string Example: This is the description under the video.
file_name optional	미디어 라이브러리 객체의 파일 이름입니다. 최대 길이: 255입니다. 파일 이름은 ads.x.com의 Media Library UI에서 각 미디어 에셋의 미디어 상세 정보에서 확인할 수 있습니다. file_name이 설정되지 않은 경우 값은 비어 있습니다. Type: string Example: coffee.jpeg
name optional	미디어 라이브러리 객체의 이름입니다. 최대 길이: 100입니다. 이는 ads.x.com의 Media Library UI에서 각 미디어 에셋 아래에 표시되는 레이블입니다. name이 설정되지 않은 경우 레이블은 “Untitled”로 표시됩니다. Type: string Example: Latte
poster_media_key optional	업로드된 이미지의 media_key를 사용하여 동영상의 포스터 이미지를 지정합니다. 지정하지 않으면 첫 번째 프레임이 사용됩니다. 참고: 동영상에만 사용할 수 있습니다. Type: string Example: 3_890599134483242005
title optional	Tweet에 게시될 때 동영상 아래에 표시되는 제목(헤드라인)입니다. 최대 길이: 70자입니다. 기본적으로 Tweet에 표시되지 않습니다. 동영상의 title을 표시하려면 POST accounts/:account_id/tweet 엔드포인트에서 video_title 매개변수를 사용하십시오. 참고: 동영상에만 사용할 수 있습니다. Type: string Example: Video title

​

요청 예시

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "3_931236738554519552"
    }
  },
  "data": {
    "tweeted": false,
    "name": null,
    "file_name": null,
    "media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
    "media_category": "TWEET_IMAGE",
    "media_key": "3_931236738554519552",
    "created_at": "2017-11-16T19:05:14Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_type": "IMAGE",
    "updated_at": "2017-11-16T19:05:23Z",
    "deleted": false
  }
}

현재 계정의 지정된 미디어 라이브러리 객체를 업데이트합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

매개변수

Name	Description
account_id required	레버리지 계정에 대한 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연계되어 있어야 합니다. Type: string Example: 18ce54d4x5t
media_key required	요청에서 사용 중인 미디어 라이브러리 객체를 참조합니다. Type: string Example: 16_844800354743074820
description optional	Tweet에 게시될 때 동영상 아래에 표시되는 설명입니다. 최대 길이: 200자. 기본적으로 이 값은 Tweet에 표시되지 않습니다. 동영상의 description을 표시하려면 POST accounts/:account_id/tweet 엔드포인트에서 video_description 매개변수를 사용하십시오. 참고: 동영상에만 사용할 수 있습니다. Type: string Example: This is the description under the video.
file_name optional	미디어 라이브러리 객체의 파일 이름입니다. 최대 길이: 255. 파일 이름은 ads.x.com의 Media Library UI에서 각 미디어 에셋의 미디어 상세 정보에서 확인할 수 있습니다. file_name이 설정되지 않은 경우 이 값은 비어 있습니다. Type: string Example: coffee.jpeg
name optional	미디어 라이브러리 객체의 이름입니다. 최대 길이: 100. 이는 ads.x.com의 Media Library UI에서 각 미디어 에셋 아래에 표시되는 레이블입니다. name이 설정되지 않은 경우 레이블은 “Untitled”로 표시됩니다. Type: string Example: Latte
poster_media_key optional	업로드된 이미지의 media_key를 사용하여 동영상에 대한 포스터 이미지를 지정합니다. 참고: 동영상에만 사용할 수 있습니다. Type: string Example: 3_885003359340375465
title optional	Tweet에 게시될 때 동영상 아래에 표시되는 제목(헤드라인)입니다. 최대 길이: 70자. 기본적으로 이 값은 Tweet에 표시되지 않습니다. 동영상의 title을 표시하려면 POST accounts/:account_id/tweet 엔드포인트에서 video_title 매개변수를 사용하십시오. 참고: 동영상에만 사용할 수 있습니다. Type: string Example: Video title

​

예시 요청

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "16_844800354743074820",
      "title": "cat GIF",
      "description": "in space"
    }
  },
  "data": {
    "tweeted": true,
    "duration": null,
    "name": null,
    "file_name": null,
    "description": "in space",
    "media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4",
    "media_category": "TWEET_GIF",
    "poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg",
    "poster_media_key": "3_844800354743074820",
    "media_key": "16_844800354743074820",
    "created_at": "2017-10-20T09:51:54Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "cat GIF",
    "media_type": "GIF",
    "aspect_ratio": "125:79",
    "updated_at": "2017-10-23T06:37:56Z",
    "deleted": false
  }
}

현재 계정의 지정된 미디어 라이브러리 객체를 삭제합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

Parameters

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스의 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
media_key required	요청에서 작업 중인 미디어 라이브러리 객체에 대한 참조입니다. Type: string Example: 7_860318603387600896

​

예시 요청

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896

​

예시 응답

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "7_860318603387600896"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 14330,
    "name": "mountains-on-ads.x.com",
    "file_name": "mountains.mp4",
    "description": "",
    "media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4",
    "media_category": "TWEET_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg",
    "poster_media_key": "3_860318839740915712",
    "media_key": "7_860318603387600896",
    "created_at": "2017-05-05T02:21:53Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "uploaded on ads.x.com",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-05-05T02:26:58Z",
    "deleted": true
  }
}

​

투표 카드

Postman에서 실행

​

GET accounts/:account_id/cards/poll

현재 계정과 관련된 일부 또는 모든 투표 카드의 세부 정보를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/poll

​

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_ids optional	쉼표로 구분된 식별자 목록을 지정해 응답을 원하는 투표 카드로만 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: 57i77
count optional	각 개별 요청에서 가져오려는 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 페이지의 결과를 가져오기 위한 cursor를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
q optional	name으로 카드를 제한하기 위한 선택적 쿼리입니다. 모든 카드를 가져오려면 이 매개변수를 생략하세요. 최대 길이: 80자입니다. Note: 대소문자를 구분하지 않는 접두사(prefix) 일치로 동작합니다. Type: string Example: night
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: created_at-asc
with_deleted optional	삭제된 결과를 요청에 포함합니다. Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count 응답 속성을 포함합니다. Note: 이 매개변수와 cursor는 동시에 사용할 수 없습니다. Note: total_count를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200회로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

​

요청 예시

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77

​

응답 예시

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_ids": [
        "57i77"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_poster_height": "9",
      "name": "최고의 해안 투표",
      "start_time": "2018-01-09T04:51:34Z",
      "first_choice": "East",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
      "content_duration_seconds": "8",
      "second_choice": "West",
      "end_time": "2018-01-16T04:51:34Z",
      "id": "57i77",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
      "created_at": "2018-01-09T04:51:34Z",
      "duration_in_minutes": "10080",
      "card_uri": "card://950590850777497601",
      "updated_at": "2018-01-09T04:51:34Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_POLLS"
    }
  ]
}

현재 계정에 연결된 특정 투표 카드를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id

​

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_id required	요청에서 사용하려는 투표 카드에 대한 참조입니다. Type: string Example: 57i8t
with_deleted optional	요청에 삭제된 결과를 포함할지 여부입니다. Type: boolean Default: false Possible values: true, false

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t

​

응답 예시

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_id": "57i8t",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "text only poll",
    "start_time": "2018-01-09T05:03:05Z",
    "first_choice": "Morning",
    "second_choice": "Evening",
    "end_time": "2018-01-11T05:03:05Z",
    "id": "57i8t",
    "created_at": "2018-01-09T05:03:05Z",
    "duration_in_minutes": "2880",
    "card_uri": "card://950593749658189824",
    "updated_at": "2018-01-09T05:03:05Z",
    "deleted": false,
    "card_type": "TEXT_POLLS"
  }
}

​

POST accounts/:account_id/cards/poll

지정된 계정에 연결된 새 투표 카드(poll card)를 생성합니다. 이 엔드포인트는 이미지, 동영상 또는 미디어 없이 투표 카드를 생성할 수 있습니다. 미디어가 포함된 투표는 Media Forward Polls라고 합니다.

참고: Media Forward Polls 제품은 베타 단계이며 PROMOTED_MEDIA_POLLS 계정 기능이 필요합니다.

참고: 투표 카드는 PUT을 사용해 업데이트할 수 없습니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/poll

​

Parameters

Name	Description
account_id required	레버리지 계정에 대한 식별자입니다. 리소스의 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 파라미터입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
duration_in_minutes required	투표가 열려 있을 시간(분 단위)입니다. 지정된 duration_in_minutes 이후에는 투표가 종료되며 더 이상 투표를 받을 수 없습니다. 이는 응답의 end_time에 해당합니다. 참고: 이는 카드가 Tweet에 추가될 때가 아니라 카드가 생성되는 즉시 시작됩니다. Type: int Min, Max: 5, 10080
first_choice required	첫 번째 투표 선택지입니다. 최대 길이: 25자. Type: string Example: One
name required	카드의 이름입니다. Type: string Example: poll card
second_choice required	두 번째 투표 선택지입니다. 최대 길이: 25자. Type: string Example: Two
fourth_choice optional	네 번째 투표 선택지입니다. 최대 길이: 25자. 참고: 이 파라미터를 사용할 경우 첫 번째, 두 번째, 세 번째 선택지가 설정되어 있어야 합니다. Type: string Example: Four
media_key optional	이 카드에 사용될 미디어 라이브러리의 이미지 또는 동영상의 media_key입니다. 이 필드는 쓰기 전용 필드입니다. 응답에서 API가 이 미디어에 대한 X URL을 제공합니다. 참고: 이미지 또는 동영상은 계정의 미디어 라이브러리에 존재해야 합니다. 참고: 최소 이미지 너비는 800px이어야 하며, 너비:높이 비율은 1.91:1이어야 합니다.
third_choice optional	세 번째 투표 선택지입니다. 최대 길이: 25자. 참고: 이 파라미터를 사용할 경우 첫 번째와 두 번째 선택지가 설정되어 있어야 합니다. Type: string Example: 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

​

응답 예시

{
  "request": {
    "params": {
      "first_choice": "East",
      "name": "best coast poll",
      "second_choice": "West",
      "media_key": "13_950589518557540353",
      "duration_in_minutes": 10080
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "best coast poll",
    "start_time": "2018-01-09T04:51:34Z",
    "first_choice": "East",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
    "content_duration_seconds": "8",
    "second_choice": "West",
    "end_time": "2018-01-16T04:51:34Z",
    "id": "57i77",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
    "created_at": "2018-01-09T04:51:34Z",
    "duration_in_minutes": "10080",
    "card_uri": "card://950590850777497601",
    "updated_at": "2018-01-09T04:51:34Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_POLLS"
  }
}

현재 계정에 속한 지정된 투표 카드를 영구적으로 삭제합니다.

참고: 이는 완전 삭제입니다. 따라서 삭제된 카드는 복구할 수 없습니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id

​

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에 대해 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_id required	요청에서 사용하는 투표 카드에 대한 참조입니다. Type: string Example: 57i9t

​

예시 요청

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t

​

예시 응답

{
  "data": {
    "name": "poll with image",
    "start_time": "2018-01-09T05:10:51Z",
    "id": "57i9t",
    "created_at": "2018-01-09T05:10:51Z",
    "updated_at": "2018-01-09T05:11:04Z",
    "deleted": true,
    "card_type": "IMAGE_POLLS"
  },
  "request": {
    "params": {
      "card_id": "57i9t",
      "card_type": "poll",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

Preroll Call To Actions

Postman에서 실행

​

GET accounts/:account_id/preroll_call_to_actions

현재 계정의 line item에 연결된 프리롤 Call-To-Action(CTA) 중 일부 또는 전체의 세부 정보를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions

​

매개변수

Name	Description
account_id required	사용하는 계정의 식별자입니다. 리소스 경로 내에 표시되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
line_item_ids optional	쉼표로 구분된 식별자 목록을 지정하여, 응답을 지정된 라인 아이템과 연결된 preroll CTA로만 제한합니다. 최대 200개의 ID를 지정할 수 있습니다. Type: string Example: 8v53k
count optional	각 개별 요청에서 조회할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참고하세요. Type: string Example: 8x7v00oow
preroll_call_to_action_ids optional	쉼표로 구분된 식별자 목록을 지정하여, 응답을 원하는 preroll CTA로만 제한합니다. 최대 200개의 ID를 지정할 수 있습니다. Type: string Example: 8f0
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참고하세요. Type: string Example: created_at-asc
with_deleted optional	요청에 삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count 응답 속성을 포함합니다. 참고: 이 매개변수와 cursor는 동시에 사용할 수 없습니다. 참고: total_count를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200회로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k

​

응답 예시

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_ids": [
        "8v53k"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8v53k",
      "call_to_action_url": "https://www.x.com",
      "call_to_action": "VISIT_SITE",
      "id": "8f0",
      "created_at": "2017-07-07T19:28:40Z",
      "updated_at": "2017-07-07T19:28:40Z",
      "deleted": false
    }
  ]
}

이 계정에 연결된 특정 콜투액션(CTA)을 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

매개변수

Name	Description
account_id required	사용하는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id required	요청에서 사용 중인 preroll call to action에 대한 참조입니다. Type: string Example: 8f0
with_deleted optional	요청에 삭제된 결과를 포함할지 여부입니다. Type: boolean Default: false Possible values: true, false

​

요청 예시

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

​

예시 응답

{
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  }
}

​

POST accounts/:account_id/preroll_call_to_actions

PREROLL_VIEWS 라인 아이템에 대한 선택적 CTA(Call-to-Action)를 설정합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions

​

매개변수

Name	Description
account_id required	활용 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
call_to_action required	광고에 표시되는 버튼의 CTA 텍스트입니다. Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url required	CTA 버튼 클릭 시 사용자가 리디렉션될 URL입니다. Type: string Example: https://www.x.com
line_item_id required	요청에서 작업 중인 라인 아이템(line item)을 참조하는 값입니다. Type: string Example: 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

​

응답 예시

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "8v53k",
      "call_to_action": "VISIT_SITE",
      "call_to_action_url": "https://www.x.com",
      "account_id": "18ce54d4x5t"
    }
  }
}

PREROLL_VIEWS 라인 아이템의 선택적 Call-to-Action(CTA)을 업데이트합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

매개변수

Name	Description
account_id required	활용하는 계정을 식별하는 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id required	해당 요청에서 사용하는 preroll CTA에 대한 참조입니다. Type: string Example: 8f0
call_to_action optional	광고에 표시되는 버튼의 CTA 텍스트입니다. Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url optional	CTA 버튼을 클릭했을 때 사용자를 리디렉션할 URL입니다. Type: string Example: https://www.x.com

​

요청 예시

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW

​

예시 응답

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "WATCH_NOW",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-09-09T05:51:26Z",
    "deleted": false
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "call_to_action": "WATCH_NOW",
      "account_id": "18ce54d4x5t"
    }
  }
}

현재 계정의 지정된 프리롤 콜투액션(CTA)을 삭제합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id required	요청에서 사용 중인 프리롤 CTA에 대한 참조입니다. Type: string Example: 8f0

​

예시 요청

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

​

응답 예시

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-08-30T06:08:21Z",
    "deleted": true
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

예약된 Tweet

Postman에서 실행

​

GET accounts/:account_id/scheduled_tweets

현재 계정과 연관된 일부 또는 모든 예약된 Tweet의 세부 정보를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets

​

매개변수

이름	설명
account_id required	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
count optional	요청당 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 100 Min, Max: 1, 200
cursor optional	다음 페이지의 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참고하세요. Type: string Example: c-j3cn6n40
user_id optional	Scheduled Tweets를 조회할 사용자를 지정합니다. 설정하지 않으면 계정의 FULL 프로모션 대상 사용자가 기본값으로 사용됩니다. Type: long Example: 756201191646691328

​

요청 예시

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1

​

응답 예시

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name": "test name",
      "completed_at": "2017-06-18T22:00:05Z",
      "text": "당신이 원하는 곳",
      "user_id": "756201191646691328",
      "scheduled_status": "SUCCESS",
      "id": "875828692081037312",
      "nullcast": true,
      "created_at": "2017-06-16T21:33:27Z",
      "scheduled_at": "2017-06-18T22:00:00Z",
      "card_uri": null,
      "updated_at": "2017-06-19T18:02:20Z",
      "tweet_id": "876560168963645440",
      "media_keys": []
    }
  ],
  "next_cursor": "c-j41uw400"
}

현재 계정에 연결된 특정 예약된 Tweet을 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

매개변수

이름	설명
account_id required	레버리지 계정을 식별하는 값입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	요청에서 조작하려는 Scheduled Tweet을 참조하는 값입니다. Type: string Example: 917438609065623552

​

예제 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552

​

응답 예시

{
  "request": {
    "params": {
      "scheduled_tweet_id": "917438609065623552"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

​

POST accounts/:account_id/scheduled_tweets

계정의 전체 프로모션 가능 사용자(기본값) 또는 as_user_id 매개변수로 지정한 사용자에 대한 예약된 Tweet을 생성합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets

​

Parameters

Name	Description
account_id required	사용할 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 파라미터입니다. 지정한 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
scheduled_at required	Tweet이 게시(또는 라이브)되어야 하는 시간을 ISO 8601 형식으로 지정합니다. 참고: Tweet은 최대 1년 뒤까지 예약할 수 있습니다. 참고: Tweet은 초 단위가 무시되므로 분 단위로만 예약해야 합니다. Type: string Example: 2017-12-31T23:59:00Z
as_user_id required	Tweet을 대신 게시하려는 광고주의 사용자 ID입니다. 광고주는 ads.x.com을 통해 자신의 광고 계정에 있는 귀하의 핸들(들)에 대한 액세스 권한을 부여해야 합니다. 이 권한을 통해 광고주의 OAuth 토큰이 아니라 귀하의 핸들을 위한 OAuth 토큰을 사용하여 API를 호출할 수 있습니다. Type: long Example: 756201191646691328
text sometimes required	상태 업데이트의 텍스트입니다. media_keys가 지정되지 않은 경우 필수입니다. Type: string Example: just setting up my twttr
card_uri optional	사용 가능한 경우, 카드 응답의 card_uri 값을 사용하여 Tweet에 카드를 연결합니다. Type: string Example: card://855591459410511943
media_keys optional	쉼표로 구분된 식별자 목록을 지정하여 Tweet에 미디어를 연결합니다. 최대 4장의 이미지, 1개의 애니메이티드 GIF 또는 1개의 동영상을 포함할 수 있습니다. 참고: 미디어 에셋은 계정의 Media Library에 있어야 합니다. Type: string Example: 13_1153584529292270722
nullcast optional	nullcast(또는 “Promoted-only”) Tweet을 생성할지 여부입니다. Type: boolean Default: true Possible values: true, false
name optional	예약된 Tweet의 이름입니다. 최대 길이: 80자. Type: string Example: 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

​

예시 응답

{
  "request": {
    "params": {
      "media_keys": [
        "3_917438348871983104"
      ],
      "scheduled_at": "2018-01-01T00:00:00Z",
      "as_user_id": 756201191646691328
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

현재 계정의 지정된 예약 Tweet을 업데이트합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

매개변수

Name	Description
account_id required	활용 중인 계정에 대한 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	요청에서 작업 중인 Scheduled Tweet에 대한 참조입니다. Type: string Example: 870321875435442177
card_uri optional	사용 가능한 경우, 어떤 카드 응답에서든 반환된 card_uri 값을 사용하여 Tweet에 카드를 연결합니다. Note: 값을 지정하지 않고 매개변수만 지정하면 설정이 해제(제거)됩니다. Type: string Example: card://875146925316386347
media_keys optional	쉼표로 구분된 식별자 목록을 지정하여 Tweet에 미디어를 연결합니다. 이미지는 최대 4개, 애니메이션 GIF는 1개, 동영상은 1개까지 포함할 수 있습니다. Note: 미디어 에셋은 계정의 Media Library에 있어야 합니다. Note: 값을 지정하지 않고 매개변수만 지정하면 설정이 해제(제거)됩니다. Type: string Example: 13_1153584529292270722
nullcast optional	nullcast(또는 “Promoted-only”)된 Tweet을 생성할지 여부입니다. Type: boolean Possible values: true, false
scheduled_at optional	Tweet이 게시되거나 라이브로 전환되어야 하는 시간을 ISO 8601 형식으로 표현한 값입니다. Type: string Example: 2017-12-31T23:59:59Z
text optional	상태 업데이트의 텍스트입니다. Type: string Example: just setting up my twttr
name optional	Scheduled Tweet의 이름입니다. 최대 길이: 80자. Type: string Example: Tweet with name

​

요청 예시

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice

​

예시 응답

{
  "request": {
    "params": {
      "scheduled_tweet_id": "875057751231037440",
      "text": "winter solstice"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "SCHEDULED",
    "text": "winter solstice",
    "user_id": "756201191646691328",
    "id": "875057751231037440",
    "nullcast": true,
    "created_at": "2017-06-14T18:30:00Z",
    "scheduled_at": "2017-12-21T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T18:30:00Z",
    "tweet_id": null,
    "media_keys": []
  }
}

현재 계정의 지정된 예약 Tweet을 영구적으로 삭제합니다.

참고: 이는 복구할 수 없는 영구 삭제(hard delete)입니다. 따라서 삭제된 예약 Tweet을 다시 조회할 수 없습니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

매개변수

Name	Description
account_id required	레버리지 계정에 대한 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	이 요청에서 조작하려는 Scheduled Tweet을 참조합니다. Type: string Example: 870321875435442177

​

예시 요청

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776

​

응답 예시

{
  "request": {
    "params": {
      "scheduled_tweet_id": 875064008595787776
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "DELETED",
    "text": "hello, world",
    "user_id": "756201191646691328",
    "id": "875064008595787776",
    "nullcast": true,
    "created_at": "2017-06-14T18:54:52Z",
    "scheduled_at": "2017-06-15T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T19:01:16Z",
    "tweet_id": null,
    "media_keys": []
  }
}

​

Tweet 미리보기

Postman에서 실행하기

​

GET accounts/:account_id/tweet_previews

게시된 Tweet, 예약된 Tweet, 초안 Tweet을 미리 볼 수 있습니다.

• 하나의 API 요청으로 여러 Tweet(최대 200개까지) 미리보기를 지원합니다.
• Tweet 레이아웃과 스타일을 정확하고 최신 상태로 렌더링합니다.
• 최신 포맷과 모든 카드 유형을 지원합니다.
• iframe을 반환합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/tweet_previews

​

매개변수

Name	Description
account_id 필수	레버리지드 계정(leveraged account)의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
tweet_ids 필수	쉼표로 구분된 식별자 목록입니다. 최대 200개의 ID를 제공할 수 있습니다. 참고: ID는 지정된 tweet_type에 해당해야 합니다. 예를 들어 Scheduled Tweet ID를 전달하고 tweet_type=PUBLISHED를 지정한 경우, 해당 ID에 대한 미리보기는 반환되지 않습니다. Type: long Example: 1122911801354510336,1102836745790316550
tweet_type 필수	지정된 tweet_ids에 대한 Tweet 유형입니다. Type: enum Possible values: DRAFT, PUBLISHED, SCHEDULED

​

요청 예시

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED

​

응답 예시

{
  "request": {
    "params": {
      "tweet_ids": [
        "1122911801354510336",
        "1102836745790316550"
      ],
      "tweet_type": "PUBLISHED",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "tweet_id": "1122911801354510336",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAANVYW2%2FbNhT%2BKwJf59iiZDuSgWLI0suyrUXbZBuGaiAoibbZUKRGUk7TIP99h6Jsy4mdC5CX%2BiUiz%2F0cfueQuUH2ijGLZsENKjSjlpWEwhK9VzI4qXUQpQE%2BnuF4FofBTyH8gijEKRogXqIZxlGUYpyEOJ6MJziM46kjEGM1qNhDBbl5IwSx7JszsuIlU8EVyw23DGhWN7JwPqDZnArDBqjkphb0uhUgmsoFQ7Mv4QDH%2Fw4Qk5Zbzgya3aAlNUtLF%2FD9BSjmusqV6BaNYZpUjlnJ9Zb2xFtgVY0uQCnKmjCMCxosNZu%2FytDS2trMslE2oqU5ojUf2ituLdPDQlUZCjQTwCXVXAmhrjIvzi48T3BSmuBUVbUC214x6PEsLnWSaFYLiEpBqqhtDHHZlJCZA0Sf0fsMbWz7ZTvSIUkD1WaSSFqxNdlJuFw6fceTKdQZp3g6nk5THEdJr7D3iRCU14ROPp4F74sLZuycFi7YHUMIElkVdksVCuoNhQHSOZXBWyhxwU2hBsHpCWoLtfauZKCJ1x3zmbQqcHq4XARUlgHYNSBQa2VZ0T9BvkBMG1KoRsKpO8KwqTmT5c6W4MYd%2Fm7H29xBxMWyCX5rRBDhACezyXQWJVtEtCebruAwwUne0dvYgqj53LCNVssrRr4ruUn8ginCJM1Fz%2B0V03zOexv%2BLOzqFgAI8IxJsF4oaTXPG6sg1LvauCEWUmsEBfK%2BXcjqPSHI5ZwLRnJaXC40WHXZEU4ehe0P7eXhFV0w0lauRZEHUW4cgKpFC59Ry2OykV2yavMXZ6N8MawhpIf1khabnXbzUuotrO%2BFvjeWetfYDi8YA3TE4yTGx%2BNJMgnTJJpko9cXvxefT%2BtzIpWuqBh%2BrftePBTZixvLqZTQGbYxPWjHc3tDdzCfjfAYvqbROMY9%2FYLLy8PnxEDHz6kmudIlePEoHyzEYa52KhykAlrunZ%2FtYGFz2ghLOuZD%2B3ekfDPhDnUeun4D2up%2FDTQjYti2eUhlAcG%2BvZkN9jcoJPa6dh1RukZw2zaBTdtRkB0uofVs5GAIFmxL30J9vadZO8jX3SH07ch1oz1bW4x3Yn3UK2N4DkMCYoGxzFfb6KEv137cbppqRwP%2FC6pLR%2BoafTRJpnEaHuPpDFJZKdLOerKd9f4AOqn2%2FOFwPI5DHKZpGOPpJBmnrqU6cpuouxh0hCNHOALCETdHJas1a%2B8OQy5XVMAQG6CcS8jjgsC68Y539olZKm2ZhN7eKr5BXTXOLz6ffXjnxhZkeC25AxQLAMlG32nJ%2Fjz%2F6zVOXO1cQaDypGy0b6WGwVZpnqA4GjsF7o4DcLjipV0%2BQQjGzVZobZyXT5GMSQroPR5HyRiuZfAVJWFP2ZLxxdI%2BQVHqhFZUcnv9xBSWbMUEHCDdv0k5LeualA5Bzy3HQa1dQOpKdlekR5Xuudb0EiPMs31rj3y%2Fq9KqFnx%2B7bGQje5XAhqvyEbmk%2F7FvEmrt6sPrE5Pvw2ruEl%2Bhuvtq8h5BLde17AedeT1OjXBR%2Bg4cxgG%2FWy%2FdKJBkNHqxXO0qmi9L1NDR%2BiZ9zPUwLzr2z97f%2FLujbtxt9TO%2Bg16ZPjtuEDssqny%2FcUCiWz0T56%2F%2B%2FTr6u%2FPX9Xbhf7jezdvOyxjYBygNayOI1hQ0c2I2zvu%2F7COE0H1j%2Bz%2Btx8wgHY0Pnt49aDbPs14zsglu%2B4mcatvo7xedw2w0P%2BGTsAL1pv18No9qTlqHy3Gv89w7LBJmxLeWTu8cBkom6J9xcF8bopLtonJGd6%2BaG4HAWpvDv5VJv2%2FDIKbzSYsrG7Y7e3%2FCm%2FIC8QQAAA%3D'>"
    },
    {
      "tweet_id": "1102836745790316550",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAO1YbW%2FbNhD%2BK4K%2Bzo3eZdlAMQQttqZrt6FNEXRVIVASJTOhSIWkHDeB%2F%2FuOomXLb%2BuHdQWGzV8s3T13vCOPz539ZKsHjJU9t57sQmCkcJkheLWvO2y9RcJyI8udzkN%2F7ofWDy58LN%2F1ZvbEJqU99zzXT4J4GkbTmRt4cRS5WpFJJcDFCS3YVR2lmcIrvcgNWmJpLZRq5Tx1UkddFDx16mUU8Lv4UhQAV6JjhQ7LnleISjyxSyJbir70PjKBWI3t%2BSd3En2e2JgpogiW9vzJXiC5UKiG50%2BgkV%2BanNPNSyexyBoN5mwQiUHZ4JIgeHwyGbpumLjh1PcDfxZ6XpSE4wyPtXpnWEkKHcSneOLPBpcZLAEmOtk%2B1zaXF%2BqBNDXk3KSOTkY9ZEtSYp6pRdfkqXPCPdh1qQNWYPFz%2BfHls7v7y6s3dZm%2Fci9u29oeLZb1%2B7pZUv6ja%2B5SO3uOw6kZaEsKHYhSWJhQ9rB41SJWQiUe%2BR2boJY0hcJSVajAqSMVUp2EBI6rLnX6FEGnC%2BpLi3UEC644vEryaOqlz18%2FPMCp6zpebL4F1hgwKQRv7bXZ4a4ZoL5rsPE0GmErojRUNojSDTJODDBIgmMgRULX8cblBjn13UMkQCu4pZ3og16vP6%2F1dincb9e4%2FP8v4%2F9EGfeSf2UZm%2BMirOIaj2SLC03nwMlQcV480RVXdr2AZQ2hlEhdx9MYnC2RIIgp2dd3ThSgwHUSQBKgLTiDCwE1Mdqi1Gna8MQR98pzxfQXZQT61IlDdxXEcC7Rm1fsHl96H8sau%2Fer1xew2I%2FQfJ4HsCmjCP0o%2Fr4Rwo6svAQivLvqXn14mRD%2FD%2BnWuX91NkJv%2Bp1D1GWyghJJnbD56HePt%2FjXG%2FJbVd3cHsR4EBFqW0qKvjxSZ%2FWsaXH94d2bbxhdS1Nn5r17CF7cTMurt6%2Ffh7fJRRN0yRDT5wMyntioLIkOCNHM8NdQ3sDLVAetGQTLQpBWw4wANzkuS5RrAEw7MOE0nGFFHo2on3oM0UveiUK7STvXDQpkLQSunqejXFEp9wjJtgSmgGC84pTyh9SY4muDsS5LaXyBqdH0xJ8J3FKYsHhm6CjTPYTB4HZGafrIMaAftE7bblTnLGGPMGYZQw0e1NpC76X2N41iGEO9mReHcTzzAj8ZtbNjJSRlPNmXv19Zb4vrDd1q4hwvZO%2BRMWgpNxUGqveIWT%2FBuFkQWfCJ9eJyKDUT3f6xXjHFLe2HsNqCJmDBuhIMWsEV8NxomjXngoXMCt4xGIqfeSAUBDr6ngjoT8%2FmG4lZc39gX3TW645avmd5yTyK536yG9hjPXijJdQPgajGfjtVZLyqJN56VaTB2SOU4CCogacx09W4C3uJBanISGBqYd83heEcIsPMNnwiSN4pDqkeeiMyA%2F5hkiJQn5LqHnBoBHtZEYqzHBV3tYBV9e5QbW%2B7%2Fcc%2BiSENqvHhFIP2J4oeA01YLXCz%2FfZSJ68vWlZ%2Fxe%2BJgeUbuFdkSwY7%2FclcDqajPSwsBrcjCJPAg8kiidxZ4kep8%2FL6l%2BLdi%2FZ9xriAVr8Zh45W%2Bfoo9vcXyxFjwAyHJH5mHYM2Cx3ceWD2EJ5iPwy8kX9K2N35OpHQE3IkspyLEqL4Kg5e6HlU%2Fwv1rBZuy1H97H7k4gp1VGUb8Dn5gZUhE6Jvnbm6RgC0et8BGWUS78iDcQU32NCb3N797S0c2izTRLDuSWBLOxx2hzCgnq0dzMQF3ul3V32QCdz%2FzzCwg2voSLPRCdHujm%2FMxreeS0lyaBKQi4Rmu9xlD7zcmiF4S6pD%2Bxxz0Xpi6TNouOFTZv6LsJ62QnjRfXi9%2FhONbe6QHREAAA%3D%3D'>"
    }
  ]
}

​

Tweets

Postman에서 실행

​

GET accounts/:account_id/tweets

계정의 전체 프로모션 대상 사용자(기본값) 또는 user_id 매개변수에 지정된 사용자의 Tweet 상세 정보를 가져옵니다. 이 사용자는 계정에 포함된 promotable users 중 어느 것이든 될 수 있습니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/tweets

​

매개변수

Name	Description
account_id required	레버리지드 계정에 대한 식별자입니다. 리소스의 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
tweet_type required	지정된 tweet_ids에 대한 Tweet type입니다. Type: enum Possible values: DRAFT, PUBLISHED, SCHEDULED
count optional	각 요청당 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: AAAAAFhLRpQLNF-sGBSgAA
include_mentions_and_replies optional	사용 가능한 Tweet 목록에서 멘션 및 답글을 필터링할지 여부입니다. Type: boolean Default: false Possible values: true, false
name optional	name으로 Tweet을 범위 지정하기 위한 선택적 쿼리입니다. 이 매개변수를 생략하면 모든 Tweet을 조회합니다. 최대 길이: 80자. Note: 대소문자를 구분하지 않는 접두어 일치 검색을 수행합니다. Type: string Example: dtc
timeline_type optional	널캐스트(nullcast, “Promoted-only”) Tweet, 오가닉 Tweet 또는 둘 다를 반환할지 여부입니다. Type: enum Default: NULLCAST Possible values: ALL, NULLCAST, ORGANIC
trim_user optional	Tweet 응답에서 user 객체를 제외할지 여부입니다. 활성화하면 반환되는 user 객체 중 Tweet 작성자의 user ID만 포함됩니다. Type: boolean Default: false Possible values: true, false
tweet_ids optional	식별자의 쉼표로 구분된 목록입니다. 최대 200개의 ID를 제공할 수 있습니다. Note: ID는 지정된 tweet_type과 일치해야 합니다. 예를 들어 예약된(Scheduled) Tweet ID가 전달된 경우, 응답에 해당 Tweet이 반환되려면 tweet_type이 반드시 SCHEDULED여야 합니다. Type: long Example: 1122911801354510336,1102836745790316550
user_id optional	Tweet 범위를 제한할 사용자를 지정합니다. 설정되지 않은 경우 계정의 FULL promotable user가 기본값으로 사용됩니다. Type: long Example: 756201191646691328

​

요청 예시

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true

​

응답 예시

{
  "request": {
    "params": {
      "tweet_ids": [
        "1166476031668015104"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "name": null,
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        9
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1166476031668015104",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "id": 1166476031668015104,
      "in_reply_to_status_id": null,
      "conversation_settings": "EVERYONE",
      "nullcast": true,
      "created_at": "Tue Aug 27 22:22:12 +0000 2019",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello, v6",
      "lang": "es",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1166476031668015104"
    }
  ]
}

​

POST accounts/:account_id/tweet

계정의 전체 프로모션 가능 사용자(기본값) 또는 as_user_id 매개변수에 지정된 사용자에 대해 Tweet을 생성합니다. nullcasted(기본값) 및 오가닉 Tweet 생성이 모두 지원됩니다. Nullcasted Tweet은 공개 타임라인에 표시되지 않으며 팔로워에게 노출되지 않습니다. 두 유형 모두 캠페인에서 사용할 수 있습니다.

인증된 사용자가 이 계정의 FULL 프로모션 가능 사용자가 아닌 경우, GET accounts/:account_id/authenticated_user_access 엔드포인트에 요청을 보내 이 사용자를 대신해 Tweet을 작성할 권한이 있는지 확인해야 합니다. TWEET_COMPOSER 권한이 있으면, 사용자가 이 엔드포인트를 사용해 FULL 프로모션 가능 사용자를 대신하여 nullcasted Tweet을 생성할 수 있음을 의미합니다.

미디어에 대해 upload.x.com 엔드포인트를 사용할 때는, 이 엔드포인트에 전달하는 as_user_id 값과 동일한 user_id 값을 additional_owners 매개변수에 전달해야 합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/tweet

​

매개변수

Name	Description
account_id required	활용 중인 계정에 대한 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
as_user_id required	광고주를 대신해 Tweet을 게시하는 광고주의 user ID입니다. 광고주는 ads.x.com에서 자신의 광고 계정에 대해 사용자 핸들(또는 여러 핸들)에 대한 액세스 권한을 부여해야 합니다. 이 권한을 통해 광고주의 토큰이 아니라 사용자 본인의 핸들의 OAuth 토큰을 사용해 API를 호출할 수 있습니다. Type: long Example: 756201191646691328
text sometimes required	상태 업데이트의 텍스트입니다. media_keys가 지정되지 않은 경우 필수입니다. Type: string Example: hello, world
card_uri optional	사용 가능한 경우, 카드 응답에 포함된 card_uri 값을 사용해 Tweet에 카드를 연결합니다. Type: string Example: card://853503245793641682
conversation_settings optional	이 Tweet에 누가 답글을 달 수 있는지 선택합니다. 언급된 사용자는 항상 답글을 달 수 있습니다. Note: 이 필드는 POST 요청 응답에서는 반환되지 않지만, GET 요청을 보낼 때는 반환됩니다. Note: 이 매개변수는 Ads API v8 이상에서만 작동합니다. Type: enum Default: EVERYONE Possible values: EVERYONE, FOLLOWING, MENTIONED_USERS
media_keys optional	쉼표로 구분된 식별자 목록을 지정해 Tweet에 미디어를 연결합니다. 최대 4장의 이미지, 1개의 애니메이션 GIF 또는 1개의 동영상을 포함할 수 있습니다. Type: string Example: 13_1153584529292270722
name optional	Tweet의 이름입니다. 최대 길이: 80자. Type: string Example: Tweet with name
nullcast optional	nullcast된(또는 “Promoted-only”) Tweet을 생성할지 여부입니다. Note: 오가닉 Tweet(nullcast=false)은 인증된 사용자에 대해서만 생성할 수 있습니다. Type: boolean Default: true Possible values: true, false
trim_user optional	Tweet 응답에서 user 객체를 제외할지 여부입니다. 활성화하면 Tweet 작성자의 user ID만 반환됩니다. Type: boolean Default: false Possible values: true, false
tweet_mode optional	응답을 호환 모드(compat)로 받을지, 확장 모드(extended)로 받을지 지정합니다. 추가 정보는 이 문서를 참조하세요. Type: string Possible values: compat, extended
video_cta optional	동영상에 대한 CTA입니다. Type: enum Possible values: VISIT_SITE, WATCH_NOW
video_cta_value optional	동영상에서 해당 CTA에 사용되는 값입니다. Type: string Example: https://dev.x.com
video_description optional	동영상 아래에 표시되는 설명입니다. 최대 길이: 200자. Type: string Example: X 광고 플랫폼과 통합하세요
video_title optional	동영상 아래에 표시되는 제목(헤드라인)입니다. 최대 길이: 70자. Type: string Example: X Ads API

​

요청 예시

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet?text=hello, world&as_user_id=756201191646691328&trim_user=true

​

응답 예시

{
  "data": {
    "created_at": "Sat Jun 24 05:08:30 +0000 2017",
    "id": 878479925472251906,
    "id_str": "878479925472251906",
    "text": "hello, world",
    "name": null,
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "<a href='"https://ads-api.x.com"' rel='"nofollow"'>Ads API Internal Test App</a>",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691328,
      "id_str": "756201191646691328"
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "hello, world",
      "trim_user": true,
      "as_user_id": 756201191646691328,
      "account_id": "18ce54d4x5t"
    }
  }
}

현재 계정의 지정된 Tweet name을 업데이트합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name

​

Parameters

Name	Description
account_id required	사용하는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 타입: string 예시: 18ce54d4x5t
tweet_id required	이 요청에서 작업하려는 Tweet에 대한 참조입니다. 타입: long 예시: 994747471329873920
name optional	Tweet의 이름입니다. 최대 길이: 80자. 타입: string 예시: Tweet with name

​

예제 요청

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name

​

예시 응답

{
  "request": {
    "params": {
      "tweet_id": 994747471329873920,
      "name": "new Tweet name",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
      "coordinates": null,
      "retweeted": false,
      "name": "new Tweet name",
      "conversation_settings": "EVERYONE",
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        5
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "994747471329873920",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 994747471329873920,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Wed Jan 01 00:00:00 +0000 2020",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello",
      "lang": "en",
      "contributors": null,
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "utc_offset": null,
        "name": "Tushar Bhushan",
        "friends_count": 1065,
        "screen_name": "imit8me",
        "location": "San Francisco, CA",
        "protected": false,
        "url": "https://tushdante.github.io",
        "profile_image_url": "http://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_background_color": "C0DEED",
        "profile_use_background_image": true,
        "is_translator": false,
        "geo_enabled": true,
        "description": "Open Sorcerer / Partner Engineer @twitter / Space Traveller | Former evangelist @sendgrid @keen_io",
        "profile_link_color": "1DA1F2",
        "id_str": "3271358660",
        "listed_count": 31,
        "default_profile_image": false,
        "followers_count": 407,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_sidebar_border_color": "C0DEED",
        "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
        "favourites_count": 5993,
        "following": null,
        "default_profile": true,
        "withheld_in_countries": [],
        "id": 3271358660,
        "profile_background_tile": false,
        "contributors_enabled": false,
        "follow_request_sent": null,
        "created_at": "Tue Jul 07 22:34:58 +0000 2015",
        "profile_sidebar_fill_color": "DDEEF6",
        "translator_type": "regular",
        "lang": null,
        "profile_text_color": "333333",
        "notifications": null,
        "verified": false,
        "time_zone": null,
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/3271358660/1474853576",
        "statuses_count": 500,
        "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
        "is_translation_enabled": false
      },
      "tweet_id": "994747471329873920"
    }
}

​

비디오 대화 카드

Postman에서 실행

참고: 카드를 Tweet에 연결하려면 card_uri 매개변수를 POST accounts/:account_id/tweet, POST statuses/update, 또는 POST accounts/:account_id/scheduled_tweets 엔드포인트와 함께 사용하세요.

​

GET accounts/:account_id/cards/video_conversation

현재 계정과 연결된 일부 또는 전체 Video Conversation Card의 상세 정보를 조회합니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation

​

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 매개변수입니다. 지정한 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_ids optional	콤마로 구분된 식별자 목록을 지정하여, 원하는 비디오 대화 카드만 응답에 포함하도록 범위를 한정합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: 5a86h
count optional	각 개별 요청에서 가져올 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
q optional	name으로 카드를 범위 지정하기 위한 선택적 쿼리입니다. 이 매개변수를 생략하면 모든 카드를 가져옵니다. 최대 길이: 80자. Note: 이 쿼리는 대소문자를 구분하지 않는 접두사 일치 방식으로 동작합니다. Type: string Example: night sky
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: created_at-asc
with_deleted optional	삭제된 결과를 응답에 포함합니다. Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count 응답 속성을 포함합니다. Note: 이 매개변수와 cursor는 동시에 사용할 수 없습니다. Note: total_count를 포함한 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200건으로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?card_ids=5a86h

​

응답 예시

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_ids": [
        "5a86h"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "id": "5a86h",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "created_at": "2018-01-30T17:53:04Z",
      "card_uri": "card://958397665015775232",
      "title": "Developers",
      "updated_at": "2018-01-30T17:53:04Z",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "deleted": false,
      "card_type": "VIDEO_CONVERSATION"
    }
  ]
}

현재 계정과 연관된 특정 Video Conversation Card를 가져옵니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id

​

매개변수

Name	Description
account_id required	활용 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_id required	요청에서 사용 중인 video conversation card에 대한 참조입니다. Type: string Example: 4i0ya
with_deleted optional	요청에 삭제된 결과를 포함할지 여부입니다. Type: boolean Default: false Possible values: true, false

​

예시 요청

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h

​

응답 예시

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  }
}

​

POST accounts/:account_id/cards/video_conversation

지정된 계정에 새 비디오 대화 카드를 생성합니다.

엔드포인트에 이미지를 업로드하는 방법에 대한 유용한 정보는 Uploading Media 문서를 참고하세요.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation

​

매개변수

이름	설명
account_id 필수	사용 중인 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
first_cta 필수	첫 번째 옵션의 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 길이에 포함되지 않음). Type: string Example: #APIs
first_cta_tweet 필수	첫 번째 CTA가 클릭될 때 사용되는 Tweet 텍스트입니다. Type: string 예시: Ads API
media_key 필수	이 카드에서 사용할 동영상의 미디어 키입니다. 참고: 동영상은 해당 계정의 Media Library에 있어야 합니다. 참고: 가로세로 비율은 16:9여야 합니다. 타입: string 예시: 13_1168079965037467209
name 필수	카드 이름입니다. Type: string Example: video conversation card
thank_you_text 필수	CTA 클릭 후 표시되는 텍스트입니다. 최대 길이: 23자. Type: string Example: Build it
title 경우에 따라 필수	카드의 제목으로, 동영상 아래와 CTA 위에 표시됩니다. 최대 길이: 23자. Type: string Note: second_cta가 설정되지 않은 경우(= not set) 필수입니다. Example: Developers
second_cta 경우에 따라 필수	두 번째 옵션에 사용할 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자 (#는 길이에 포함되지 않음). Type: string Note: title이(가) 설정되어 있지 않은 경우 필수입니다. Example: #ShareAgain
second_cta_tweet 조건부 필수	두 번째 CTA가 클릭될 때 사용되는 Tweet 텍스트입니다. 참고: second_cta가 설정된 경우 필수입니다. Type: string Example: I Heart @AdsAPI Again
poster_media_key 선택 사항	이 카드에 사용할 포스터 이미지의 미디어 키입니다. 지정하지 않으면 첫 번째 프레임이 사용됩니다. 참고: 동영상은 해당 계정의 Media Library에 있어야 합니다. Type: long Example: 3_882726458191298561
third_cta 선택 사항	세 번째 옵션에 사용할 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(# 문자는 길이에 포함되지 않음). Type: string Example: #ShareMore
third_cta_tweet 조건부 필수	세 번째 CTA가 클릭되었을 때 사용되는 Tweet 텍스트입니다. Type: string 참고: third_cta가 설정된 경우 필수입니다. 예시: I Heart @TwitterDev
fourth_cta 선택	네 번째 옵션에 대한 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(# 문자는 길이에 포함되지 않음). Type: string Example: #ShareExtra
fourth_cta_tweet 경우에 따라 필수	네 번째 CTA가 클릭될 때 사용되는 Tweet 텍스트입니다. Type: string Note: fourth_cta가 설정된 경우 필수입니다. Example: I Heart @TwitterDev Again
thank_you_url 선택 사항	감사 메시지와 함께 표시되는 URL입니다. Type: string Example: https://example.com/thankyou
unlocked_image_media_key 선택 사항	인스턴트 언락 시나리오에서 사용될 이미지의 media_key입니다. 이 필드는 쓰기 전용 필드입니다. 응답에서 API가 이 이미지에 대한 X URL을 제공합니다. 참고: 이미지는 계정의 미디어 라이브러리에 존재해야 합니다. Type: string Example: 3_883112887618682880
unlocked_video_media_key 선택 사항	instant unlock 시나리오에서 사용될 GET accounts/:account_id/media_library 엔드포인트에서 가져온 비디오의 식별자입니다. 타입: 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

​

응답 예시

{
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "video_poster_height": "9",
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "title": "Developers",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_CONVERSATION"
    }
  }
}

현재 계정 소유의 지정된 비디오 대화 카드(video conversation 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 필수	요청에서 조작 중인 Video Conversation Card를 참조하는 값입니다. Type: string Example: 5a86h
first_cta 선택 사항	첫 번째 옵션에 사용할 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 포함하지 않음). Type: string Example: #APIs
first_cta_tweet 선택 사항	첫 번째 CTA를 클릭했을 때 사용되는 Tweet 텍스트입니다. Type: string Example: Ads API
second_cta 선택 사항	두 번째 옵션용 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 문자 수에 포함하지 않음). Type: string 참고: title이 설정되지 않은 경우 필수입니다. 예시: #ShareAgain
second_cta_tweet 선택 사항	두 번째 CTA가 클릭될 때 사용되는 Tweet 텍스트입니다. 참고: second_cta가 설정된 경우 필수입니다. Type: string Example: I Heart @AdsAPI Again
third_cta 선택 사항	세 번째 옵션에 사용할 Call-To-Action(CTA) 해시태그입니다. 최대 길이: 20자(#는 길이에 포함되지 않음). Type: string Example: #ShareMore
third_cta_tweet 선택 사항	세 번째 CTA 클릭 시 사용되는 Tweet 텍스트입니다. Type: string 참고: third_cta가 설정된 경우 필수입니다. Example: I Heart @TwitterDev
fourth_cta 선택 사항	네 번째 옵션에 사용할 Call-To-Action (CTA) 해시태그입니다. 최대 길이: #을 제외하고 20자입니다. Type: string Example: #ShareExtra
fourth_cta_tweet 선택 사항	네 번째 CTA가 클릭되었을 때 사용할 Tweet 텍스트입니다. Type: string 참고: fourth_cta가 설정된 경우 필수입니다. 예시: I Heart @TwitterDev Again
media_key 선택 사항	이 카드에 사용할 동영상의 media key입니다. 참고: 동영상은 해당 계정의 Media Library에 있어야 합니다. 참고: 16:9 화면 비율이어야 합니다. Type: string Example: 13_1168079965037467209
name 선택 사항	카드 이름입니다. Type: string Example: developers card
poster_media_key 선택 사항	이 카드에서 포스터 이미지로 사용할 미디어의 media key입니다. 지정하지 않으면 첫 번째 프레임이 사용됩니다. 참고: 동영상은 계정의 Media Library에 있어야 합니다. Type: long Example: 3_882726458191298561
thank_you_text 선택 사항	CTA를 클릭한 후에 표시되는 텍스트입니다. 최대 길이: 23자. Type: string Example: Build it
thank_you_url 선택 사항	감사 텍스트와 함께 표시할 URL입니다. Type: string Example: https://example.com/thankyou
title 선택 사항	카드 제목으로, 동영상 아래, CTA 위에 표시됩니다. 최대 길이: 23자입니다. Type: string 참고: second_cta가 설정되어 있지 않은 경우 필수입니다. 예: Start a conversation
unlocked_image_media_key 선택 사항	인스턴트 언락 시나리오에서 사용할 이미지의 media_key입니다. 이 필드는 쓰기 전용입니다. 응답에서는 이 이미지에 대한 X URL을 제공합니다. 참고: 이미지는 계정의 미디어 라이브러리에 있어야 합니다. Type: string Example: 3_883112887618682880
unlocked_video_media_key 선택 사항	GET accounts/:account_id/media_library 엔드포인트에서 가져온 동영상의 식별자입니다. Type: string Example: 13_867520357225418752

​

요청 예시

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card

​

예시 응답

{
  "data": {
    "name": "developers card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T18:02:15Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_CONVERSATION",
      "card_id": "5a86h",
      "name": "developers card"
    }
  }
}

현재 계정에 속한 지정된 비디오 대화 카드(video conversation card)를 영구 삭제합니다.

참고: 이는 하드 삭제(hard delete)입니다. 따라서 삭제된 카드는 복구할 수 없습니다.

​

리소스 URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id

​

매개변수

Name	Description
account_id required	레버리지 계정에 대한 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
card_id required	요청에서 사용 중인 Video Conversation Card에 대한 참조입니다. Type: string Example: 4i0ya

​

요청 예시

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/4i0ya

​

응답 예시

{
  "data": {
    "name": "video conversation card",
    "id": "4i0ya",
    "created_at": "2017-07-07T01:36:39Z",
    "updated_at": "2017-08-23T13:29:13Z",
    "deleted": true,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0ya",
      "card_type": "video_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}