> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 크리에이티브
export const Button = ({href, children}) => {
return
;
};
## 개요
크리에이티브는 캠페인에서 프로모션 대상으로 사용할 수 있는 모든 개체를 의미합니다. 포스트에는 텍스트, 이미지, GIF, 동영상 또는 카드가 포함될 수 있습니다. 카드는 이미지 또는 동영상을 포함할 수 있습니다.
이미지, GIF 또는 동영상 크리에이티브는 [POST media/upload](/ko/x-api/media/upload-media#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](/ko/x-ads-api/creatives#cards-2)에 사용되는 에셋에 적용됩니다. 이미지는 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](/ko/x-ads-api/creatives#cards-2)에 사용되는 에셋에 적용됩니다. 지원되는 가로:세로 비율은 다음과 같습니다.
* 비디오 웹사이트: 16:9 및 1:1
* 비디오 App 다운로드: 16:9 및 1:1
* 투표: 16:9
* 비디오 대화: 16:9
* 비디오 다이렉트 메시지: 16:9
### 프로모티드 비디오
이 문서는 Ads API를 통해 비디오를 업로드하고 프로모션하는 절차에 대한 간단한 개요를 제공합니다.
Ads API는 [Tweets](/ko/x-ads-api/creatives#tweets-2) 내 프로모티드 비디오와 다음 카드에서의 프로모티드 비디오를 지원합니다.
* [Video Website](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [Video App Download](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [Video Conversation](/ko/x-ads-api/creatives#video-conversation-cards)
먼저 [POST media/upload (chunked)](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload-init.html) 엔드포인트를 사용해 비디오를 업로드합니다. 그런 다음 `media_id`를 사용해 POST accounts/:account\_id/videos 엔드포인트로 해당 비디오를 광고 계정에 연결합니다. 비디오의 `id`는 때때로 `media_key`라고도 하며 이후 요청에서 사용됩니다. 이는 정수형 값으로 시작하고, 그 뒤에 밑줄이 오며, 마지막에 긴 숫자 값이 오는 문자열입니다. 예시는 다음과 같습니다: `13_875943225764098048`.
#### Tweet에서 Promoted Video 사용
Tweet을 생성하려면 동영상의 `id`와 함께 [POST accounts/:account\_id/tweet](/ko/x-ads-api/creatives#get-accounts-account-id-tweets) 엔드포인트를 사용하세요. 이 단계에서 동영상 제목, 설명, 콜투액션(CTA)도 함께 지정할 수 있습니다. 이 값들은 사용자에게 직접 노출됩니다.
#### 카드 내 프로모티드 비디오
Video App Download 및 Video Conversation 카드는 포스터 이미지를 추가할 수 있습니다. 이러한 카드에서 사용할 이미지는 [POST media/upload](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload.html) 엔드포인트를 사용해 업로드합니다.
다음 엔드포인트 중 하나를 사용해 카드를 생성합니다.
* [POST accounts/:account\_id/cards/video\_website](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [POST accounts/:account\_id/cards/video\_app\_download](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [POST accounts/:account\_id/cards/video\_conversation](https://devcommunity.x.com/t/ads-api-version-11/168814)
비디오의 `id`와, 선택적으로 이미지의 `media_id`(포스터 이미지용)를 사용합니다.
마지막으로 POST accounts/:account\_id/tweet 엔드포인트를 사용해 Tweet을 생성합니다. 카드는 `card_uri` 매개변수를 사용해 Tweet에 연결됩니다.
#### 일반 정보
API를 통한 동영상 업로드에 대한 자세한 안내는 [Video Upload Guide](https://developer.x.com/en/docs/media/upload-media/uploading-media.html)를 참고하세요.
동영상은 프리롤 자산으로도 프로모션할 수 있습니다. 자세한 설명은 [Video Views Pre-roll Objective Guide](/ko/x-ads-api/campaign-management#video-views-preroll-objective)를 참고하세요.
* (2015-10-22 기준) 프로모션용 콘텐츠에 사용할 동영상을 업로드할 때는, [POST media/upload (chunked)](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload-init.html) 엔드포인트에 대한 모든 `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` 조회
* [GET accounts/:account\_id/scheduled\_promoted\_tweets](/ko/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets) (모든 예약된 프로모션 Tweet 목록을 조회합니다)
* [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/ko/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (`id`를 사용해 예약된 프로모션 Tweet을 조회합니다)
* [POST accounts/:account\_id/scheduled\_promoted\_tweets](/ko/x-ads-api/campaign-management#post-accounts-account-id-scheduled-promoted-tweets) (새 예약된 프로모션 Tweet을 생성합니다)
* [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/ko/x-ads-api/campaign-management#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (`id`를 사용해 기존 예약된 프로모션 Tweet을 삭제합니다)
#### 예약 Tweet 보기
* [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/ko/x-ads-api/creatives#scheduled-tweets-2) (기존 예약 Tweet 보기)
예약 Tweet은 “라이브” Tweet과는 별도의 엔터티이기 때문에, 이 Tweet을 생성하거나 수정할 때 두 가지 서로 다른 검증이 수행됩니다. 첫 번째 검증 규칙 세트는 예약 Tweet 생성 단계, 즉 다음 시점에 실행됩니다:
#### Scheduled Tweet 생성:
* 인증된 사용자가 지정된 @handle에 대해 유기적(organic) Tweet을 생성할 수 있는 권한이 있는지 확인합니다. Promoted-Only Tweet 생성 권한을 사용하려면 인증된 사용자가 [Tweet composer permissions](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/authenticated-user-access#get-accounts-account-id-authenticated-user-access)을 보유한 계정 사용자여야 합니다.
* `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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#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이 생성됩니다:
```json theme={null}
{
"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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweet-previews#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
```
```json theme={null}
{
"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](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#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'
```
```json theme={null}
{
"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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/overview)에서 재사용할 수 있어, 동일한 에셋을 여러 번 업로드하지 않아도 됩니다.
#### API 엔드포인트
* [POST media/upload](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload#post-media-upload) (미디어 업로드) 또는 [POST media/upload (chunked)](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload-init#post-media-upload-init) (청크 단위로 미디어 업로드)
* [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#post-accounts-account-id-media-library) (Media Library에 미디어를 추가)
#### 라이브러리에 추가하기
라이브러리에 미디어를 추가하는 과정은 두 단계로 구성됩니다. 먼저, [POST media/upload](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload#post-media-upload) 엔드포인트 또는 [POST media/upload (chunked)](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload-init#post-media-upload-init) 엔드포인트 세트를 사용해 미디어 자산을 업로드합니다. (당사의 멀티파트 업로드 방식에 대한 자세한 내용은 [Chunked media upload](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/uploading-media/chunked-media-upload) 가이드를 참조하세요.)
```
twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"
```
```json theme={null}
{
"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](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#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"
```
```json theme={null}
{
"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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet)*, [Tweet preview](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweet-preview)*, 그리고 [Scheduled Tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets). 우리는 media key가 모든 곳에서 지원되도록 작업을 진행 중입니다.
`aspect_ratio` 속성은 GIF 및 동영상에 대해 반환됩니다. 이는 특정 가로세로 비율만 허용하는 카드에서 사용할 미디어를 필터링하는 데 사용할 수 있습니다.
\*이러한 엔드포인트는 media key인 `video_id` 파라미터를 지원합니다.
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](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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/creatives/api-reference/cards-fetch.html#get-accounts-account-id-cards-all) 및 [GET accounts/:account\_id/cards/all/:card\_id](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/cards-fetch#get-accounts-account-id-cards-all-card-id). 첫 번째 엔드포인트는 card\_uri로 카드를 가져올 수 있고, 두 번째 엔드포인트는 카드 ID로 카드를 가져올 수 있습니다. 카드 ID는 preview\_url의 끝부분에서 확인할 수 있습니다. 위 예시에서 ID는 68w3s입니다.
### 미디어 식별하기
#### 소개
이미지, GIF, 동영상과 같은 미디어는 Tweet 및 카드에 추가할 수 있습니다. 또한 동영상은 프리롤 자산으로 사용할 수 있고 이미지는 [X Audience Platform](https://developer.x.com/en/docs/ads/measurement/overview/twitter-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 가이드](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/guides/media-library)를 참고하세요. 광고 계정의 FULL 프로모션 대상 사용자에 속한 대부분의 에셋은 라이브러리에서 찾을 수 있습니다. 다만 몇 가지 예외가 있습니다.
**미디어 가져오기**
앞에서 설명했듯이, 이미지 카드는 media ID나 media key에 대한 참조를 포함하지 않습니다. 따라서 Media Library를 통해 해당 에셋을 가져올 수 없습니다. 이는 [Account Media](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/account-media#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 에셋으로 추가됩니다.
* 특정 크기(자세한 내용은 [열거형 페이지](https://developer.x.com/content/developer-twitter/en/docs/ads/general/overview/enums)의 "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](https://developer.x.com/content/developer-twitter/en/docs/tutorials/ads-api-hierarchy-terminology#promotable-users)만 생성할 수 있습니다.
**Tweet 업데이트**
예약 및 초안 Tweet의 `nullcast` 속성은 업데이트할 수 있습니다. 예약 Tweet의 경우 Tweet의 `scheduled_at` 시간 전까지 편집할 수 있습니다. 초안 Tweet은 무기한 편집할 수 있습니다. 그러나 한 번 게시된 이후에는 Tweet을 널캐스트에서 오가닉으로, 또는 그 반대로 변경할 수 없습니다.
#### Tweet 프로모션
게시되었거나 예약된 Tweet만 프로모션할 수 있습니다. 이들 Tweet은 널캐스트(nullcast) 형태이거나 오가닉(organic)일 수 있으며, 이에 대한 제한은 없습니다. 광고주는 권한을 얻은 경우 자신이 작성한 Tweet뿐 아니라 다른 사용자의 Tweet도 프로모션할 수 있습니다. (자세한 내용은 [다른 사용자의 Tweet 프로모션](https://developer.x.com/content/developer-twitter/en/docs/tutorials/promoting-another-users-content)을 참고하세요.)
여러 개의 Tweet을 단일 캠페인에서 프로모션할 수 있습니다. 마찬가지로, 하나의 Tweet을 하나 이상의 캠페인에서 프로모션할 수 있습니다.
게시된 Tweet을 프로모션하려면 [POST accounts/:account\_id/promoted\_tweets endpoint](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/promoted-tweets#post-accounts-account-id-promoted-tweets)를 사용하세요. 이 엔드포인트는 게시된 Tweet을 라인 아이템에 연결합니다. 예약된 Tweet을 프로모션하려면 [POST accounts/:account\_id/scheduled\_promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#post-accounts-account-id-scheduled-promoted-tweets) endpoint를 사용하세요.
#### Tweet ID
게시된, 예약된, 초안 Tweet의 ID는 [숫자형](https://developer.x.com/content/developer-twitter/en/docs/basics/twitter-ids)이면서 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](https://business.x.com/en/advertising/carousels.html) 페이지를 참고하세요.
캐러셀은 다른 카드 타입과 마찬가지로 Tweet에 사용할 수 있으며, 이렇게 만든 Tweet은 프로모션할 수 있습니다. 전체 워크플로우는 이미 익숙한 것과 동일합니다:
1. 미디어 업로드
2. 카드 생성
3. Tweet 생성
4. Tweet 프로모션
유일한 차이점은 카드 생성 방식입니다. 다른 카드 생성 요청은 쿼리 매개변수를 허용하는 반면, 캐러셀 카드 생성 요청은 JSON POST 본문만 허용합니다.
#### 엔드포인트
Ads API는 캐러셀의 생성과 조회를 지원합니다.
어떤 종류의 캐러셀이든 생성하려면 [POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards) 엔드포인트를 사용하세요. 캐러셀을 조회하려면 [GET accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#app-destination)을 참조하세요.
이를 종합하면, 아래는 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](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/media-library)를 참고하세요.
미디어 에셋이 Media Library에 저장되면 [GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) 엔드포인트를 사용해 Tweet을 확인할 수 있습니다.
### 크리에이티브 메타데이터 태그 지정
#### 소개
이 가이드는 크리에이티브 파트너, 에이전시 및 크리에이티브 개발자가 X 캠페인에서 사용되는 에셋에 태그를 추가해 개별 에셋의 가치와 성과를 더 잘 파악할 수 있도록 돕기 위한 것입니다.
**참고:** 미디어 에셋은 해당 미디어 에셋을 생성한 파트너 또는 개발자만 태그해야 합니다. 미디어 에셋의 사용자가 해당 미디어 에셋을 생성하지 않았다면 메타데이터 태깅을 구현하지 마십시오.
Creative Metadata Tagging은 에셋이 X 내 어디에 업로드되든, 에셋을 업로드하는 주체가 누구이든 상관없이 크리에이티브 파트너가 제작한 이미지와 동영상에 대한 제작자 정보를 제공하는 기능입니다. 크리에이티브 에셋과 크리에이티브 파트너 간의 연결을 만들기 위해 [XMP](https://exiftool.org/TagNames/XMP.html) 표준이 사용됩니다.
#### 크리에이티브 에셋 태깅
다음 표는 각 이미지 관련 리소스의 응답에서 현재 사용 가능한 식별자 유형과 해당 속성 이름을 보여줍니다. 크리에이티브 에셋에 태그를 지정하려면 태깅 도구가 필요합니다. [ExifTool](https://exiftool.org/)은 메타 정보를 읽고, 쓰고, 편집하기 위한 플랫폼 독립적인 Perl 라이브러리와 [명령줄 애플리케이션](https://exiftool.org/exiftool_pod.html)으로 구성되어 있으며, 사용을 권장합니다. 지원되는 모든 [파일 유형](https://exiftool.org/#supported)을 확인하세요.
제공된 [ExifTool 설치 안내](https://exiftool.org/install.html)를 따라 설치하세요. macOS와 Linux에서 [exiftool 설치 명령](https://formulae.brew.sh/formula/exiftool)을 제공하여 설치를 더욱 간단하게 해 주는 [Homebrew](https://formulae.brew.sh/) 소프트웨어 패키지도 있습니다. 명령줄에서 `exiftool -ver`를 입력하여 도구의 버전 번호가 반환되는지 확인함으로써 도구가 올바르게 설치되었는지 검증할 수 있습니다. ExifTool 명령 파라미터에 대한 자세한 내용은 [ExifTool 문서](https://exiftool.org/)를 참고하세요.
크리에이티브 파트너는 새 크리에이티브 에셋이나 기존 크리에이티브 에셋에 대해 X app\_id를 contributor XMP 태그와 date 태그의 메타데이터 값으로 지정할 수 있습니다. 크리에이티브 에셋은 [미디어 업로드](https://developer.x.com/en/docs/twitter-api/v1/media/upload-media/overview) 시 기존 크기 제한을 따르게 됩니다.
**참고:** X에서 contributor XMP 태그를 사용하는 것은 메타데이터가 X에서 진행되는 캠페인에 대한 값만을 캡처하도록 보장하기 위한 것입니다.
`exiftool -contributor="" -creative_file.jpg`
`exiftool -date="" -creative_file.jpg`
app\_id는 [개발자 콘솔](https://developer.x.com/en/portal/dashboard)의 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 `
예시:
`exiftool -xmp:all -G1 eiffel_tower.jpg`
```
[XMP] XMP Toolkit : Image::ExifTool 12.30
```
```
[XMP] Contributor : 858382169
```
```
[XMP] Date : 2022:03:13
```
#### 질문이 있으신가요?
태깅과 어트리뷰션이 올바르게 설정되었는지 확인하려면, 태깅이 적용된 샘플 에셋을 [adsapi-program@x.com](mailto:adsapi-program@x.com)으로 보내 주시면 X 담당자가 검토해 드립니다.
## API 참조 문서
### 계정 미디어
#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction)을 참고하세요. 타입: string 예시: `8x7v00oow` |
| sort\_by *optional* | 지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 [Sorting](https://developer.x.com/x-ads-api/fundamentals/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` |
**참고**: 카드를 Tweet과 연결하려면 `card_uri` 매개변수를 [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets), 또는 [POST accounts/:account\_id/draft\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/draft-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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction)을 참조하세요. Type: string Example: `8x7v00oow` |
| include\_legacy\_cards *optional* | 응답에 레거시 웹사이트 및 App 카드를 포함합니다. 레거시 카드는 리소스 URL 형식이 다음과 같은 카드입니다: accounts/:account\_id/cards/:card\_type. 자세한 내용은 [이 개발자 포럼 게시물](https://devcommunity.x.com/t/new-cards-endpoints-and-carousel-ads/145782/6)을 참조하세요. Type: boolean Default: `false` Possible values: `true`, `false` |
| q *optional* | `name`으로 카드를 한정하기 위한 선택적 쿼리입니다. 모든 카드를 가져오려면 이 매개변수를 생략하세요. 최대 길이: 80자. **참고**: 대소문자를 구분하지 않는 접두사 일치(prefix matching)를 수행합니다. Type: string Example: `dtc` |
| sort\_by *optional* | 지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting)을 참조하세요. Type: string Example: `created_at-asc` |
| with\_deleted *optional* | 요청에 삭제된 결과를 포함합니다. Type: boolean Default: `false` Possible values: `true`, `false` |
지정된 계정에 연관된 새 카드를 생성합니다.
카드 생성 요청에서는 JSON 형식의 POST 본문만 허용됩니다. `Content-Type`은 `application/json`으로 설정해야 합니다.
자세한 사용 예시는 [Carousels 가이드](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://en.wikipedia.org/wiki/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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 |
`https://ads-api.x.com/12/accounts/:account_id/cards/all`
#### 매개변수
| Name | Description |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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` |
계정의 전체 프로모션 가능 사용자(기본값) 또는 `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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t` |
| as\_user\_id *required* | Tweet을 게시하려는 광고주의 사용자 ID입니다. 광고주는 [ads.x.com](https://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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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`
#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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."
}
```
### 이미지 대화 카드
**참고**: 카드를 Tweet에 연결하려면 `card_uri` 파라미터를 [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), 또는 [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets) 엔드포인트 중 하나와 함께 사용하세요.
#### GET accounts/:account\_id/cards/image\_conversation
| Name | Description |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | 레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction)을 참조하세요. Type: string Example: `8x7v00oow` |
| q *optional* | `name`으로 카드를 범위 지정하기 위한 선택적 쿼리입니다. 모두 가져오려면 이 매개변수를 생략합니다. 최대 길이: 80자. **Note**: 대소문자를 구분하지 않는 접두어(prefix) 매칭을 수행합니다. Type: string Example: `night` |
| sort\_by *optional* | 지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 [Sorting](https://developer.x.com/x-ads-api/fundamentals/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/rest/public/uploading-media)를 참고하세요.
#### 리소스 URL
`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`
#### 매개변수
| Name | Description |
| :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 활용 계정(leveraged account)의 식별자입니다. 리소스 경로 내에 나타나며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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"
}
}
}
```
현재 계정의 지정된 이미지 대화 카드를 업데이트합니다.
엔드포인트로 이미지를 업로드하는 방법에 대한 유용한 정보는 [미디어 업로드하기](https://developer.x.com/rest/public/uploading-media)를 참고하세요.
| Name | Description |
| :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 레버리지 계정에 대한 식별자입니다. 리소스의 경로 내에 나타나며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | 요청에서 사용 중인 image conversation card에 대한 참조입니다. Type: string Example: `4i0qe` |
```
{
"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 가이드](https://developer.x.com/en/docs/ads/creatives/guides/media-library)를 참고하세요.
**참고**: Media Library에 `AMPLIFY_VIDEO` 미디어 카테고리의 동영상을 추가하면 자동으로 `PREROLL` [account\_media](https://developer.x.com/en/docs/ads/creatives/api-reference/account-media#get-accounts-account-id-account-media) 에셋으로 사용할 수 있습니다.
#### 리소스 URL
`https://ads-api.x.com/12/accounts/:account_id/media_library`
#### 매개변수
| Name | Description |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 활용 중인 계정의 식별자입니다. 리소스 경로 내에 포함되며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) 엔드포인트에서 `video_title` 매개변수를 사용하십시오. **참고**: 동영상에만 사용할 수 있습니다. Type: string Example: `Video title` |
| Name | Description |
| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 레버리지 계정의 식별자입니다. 리소스의 경로 내에 나타나며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t` |
| media\_key *required* | 요청에서 작업 중인 미디어 라이브러리 객체에 대한 참조입니다. Type: string Example: `7_860318603387600896` |
지정된 계정에 연결된 새 투표 카드(poll card)를 생성합니다. 이 엔드포인트는 이미지, 동영상 또는 미디어 없이 투표 카드를 생성할 수 있습니다. 미디어가 포함된 투표는 Media Forward Polls라고 합니다.
**참고**: Media Forward Polls 제품은 베타 단계이며 `PROMOTED_MEDIA_POLLS` 계정 기능이 필요합니다.
**참고**: 투표 카드는 PUT을 사용해 업데이트할 수 없습니다.
| Name | Description |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | 레버리지 계정에 대한 식별자입니다. 리소스의 경로 내에 나타나며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts)를 제외한 모든 Advertiser API 요청에 대해 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | 요청에서 사용하는 투표 카드에 대한 참조입니다. Type: string Example: `57i9t` |
#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction)을 참고하세요. Type: string Example: `8x7v00oow` |
| preroll\_call\_to\_action\_ids *optional* | 쉼표로 구분된 식별자 목록을 지정하여, 응답을 원하는 preroll CTA로만 제한합니다. 최대 200개의 ID를 지정할 수 있습니다. Type: string Example: `8f0` |
| sort\_by *optional* | 지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 [Sorting](https://developer.x.com/x-ads-api/fundamentals/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` |
| Name | Description |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 사용할 계정의 식별자입니다. 리소스 경로에 포함되며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 파라미터입니다. 지정한 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: `18ce54d4x5t` |
| scheduled\_at *required* | Tweet이 게시(또는 라이브)되어야 하는 시간을 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 형식으로 지정합니다. **참고**: Tweet은 최대 1년 뒤까지 예약할 수 있습니다. **참고**: Tweet은 초 단위가 무시되므로 분 단위로만 예약해야 합니다. Type: string Example: `2017-12-31T23:59:00Z` |
| as\_user\_id *required* | Tweet을 대신 게시하려는 광고주의 사용자 ID입니다. 광고주는 [ads.x.com](https://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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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`
`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`
#### 매개변수
| Name | Description |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 활용 중인 계정에 대한 식별자입니다. 리소스 경로에 포함되며, [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://en.wikipedia.org/wiki/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts)를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: `18ce54d4x5t` |
| scheduled\_tweet\_id *required* | 이 요청에서 조작하려는 Scheduled Tweet을 참조합니다. Type: string Example: `870321875435442177` |
게시된 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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": "