페이지 이동경로
  • 문서>
  • 카카오 키워드광고>
  • 이미지 관리

카카오 키워드광고

이미지 관리

이 문서는 이미지 관리 API 사용 방법을 안내합니다.

이미지는 광고에 함께 노출되는 확장소재에서 사용됩니다.

이미지 목록 보기

기본 정보
메서드 URL 인증 방식
GET https://api.keywordad.kakao.com/openapi/v1/images 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
- 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

이미지의 목록을 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 종류별 이미지 관리 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
쿼리 파라미터
이름 타입 설명 필수
recentlyUsed Boolean 최근 사용한 이미지을 우선순위로보기 설정
(기본값은 false로 미입력시 최신등록 우선순위로 입력)		 X
page Integer 페이지 번호
(미입력시 0으로 입력)		 X
limit Integer 페이지당 갯수
(미입력시 10으로 입력,최대 1000)		 X

응답

본문
이름 타입 설명
id Long 이미지 ID
url String 이미지 다운로드 URL
fileName String 이미지 파일 이름
width Integer 이미지 넓이
height Integer 이미지 높이
size Integer 이미지 파일 크기
lastUsedDate String 이미지 마지막 사용 시간

예제

요청
curl -v -G GET "https://api.keywordad.kakao.com/openapi/v1/images" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"  \
    -d "recentlyUserd=false" \
    -d "page=0" \
    -d "limit=10""
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "content": [
    {
      "id": "8888888882",
      "url": "http://www.kakao.com/image1.jpg",
      "fileName": null,
      "width": 450,
      "height": 450,
      "size": 200000,
      "lastUsedDate": "2021-02-20T12:00:00.702463"
    },
    {
      "id": "8888888882",
      "url": "http://www.kakao.com/image2.jpg",
      "fileName": null,
      "width": 450,
      "height": 450,
      "size": 200000,
      "lastUsedDate": "2021-02-20T12:20:00.702463"
    }
  ],
  "page": {
    "number": 0,
    "size": 10,
    "totalElements": 2,
    "totalPages": 0
  },
  "recentlyUsed": false
}

이미지 보기

기본 정보
메서드 URL 인증 방식
GET https://api.keywordad.kakao.com/openapi/v1/images/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
- 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

이미지의 상세 정보를 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 종류별 이미지 관리 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 이미지 ID O

응답

본문
이름 타입 설명
id Long 이미지 ID
url String 이미지 다운로드 URL
fileName String 이미지 파일 이름
width Integer 이미지 넓이
height Integer 이미지 높이
size Integer 이미지 파일 크기
lastUsedDate String 이미지 마지막 사용 시간

예제

요청
curl -v -G GET "https://api.keywordad.kakao.com/openapi/v1/images/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "id": "8888888881",
   "lastUsedDate": "2021-02-20T12:00:00.702463",
   "url": "https://www.kakao.com/image1.jpg",
   "fileName": "sample.jpeg",
   "width": 450,
   "height": 450,
   "size": 200000
 }

이미지 등록하기

기본 정보
메서드 URL 인증 방식
POST https://api.keywordad.kakao.com/openapi/v1/images 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
- 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

새로운 이미지를 등록합니다.

이미지 등록을 위해 application/json과 multipart/form-data 두 가지 Content-Type을 지원합니다. 어느 방식으로 요청하더라도 등록 결과는 같습니다.

  • application/json: imageFileUrl 파라미터로 https:// 또는 https:// URL 형식의 이미지 경로 전달
  • multipart/form-data: imageFile 파라미터로 로컬 파일 경로 전달

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. 요청이 성공하면 응답 본문에 JSON 객체로 생성된 이미지 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
imageFileUrl String http:// 또는 https:// 형식의 URL형태로 요청
최대 이미지 사이즈: 450 x 450 px
최대 용량: 400 KB
지원하는 파일형식: JPG, JPEG, PNG		 O*
imageFile Multipart File 로컬 파일 경로 입력
최대 이미지 사이즈: 450 x 450 px
최대 용량: 400 KB
지원하는 파일형식: JPG, JPEG, PNG		 O*

* application/json 방식일 경우 imageFileUrl 필수, multipart/form-data 방식일 경우 imageFile 필수

응답

본문
이름 타입 설명
id Long 이미지 ID
url String 이미지 다운로드 URL
fileName String 이미지 파일 이름
width Integer 이미지 넓이
height Integer 이미지 높이
size Integer 이미지 파일 크기
lastUsedDate String 이미지 마지막 사용 시간

예제

요청: application/json 방식
curl -v -X POST "https://api.keywordad.kakao.com/openapi/v1/images" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "Content-Type: application/json" \
    -d '{
            "imageFileUrl":"httpss://www.image.com/image1.jpg"
        }'
요청: multipart/form-data 방식
curl -v -X POST "https://api.keywordad.kakao.com/openapi/v1/images" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "Content-Type: application/json" \
    -F "imageFile=@450X450_이미지_경로"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "id": "8888888881",
   "lastUsedDate": "2021-02-20T12:00:00.702463",
   "url": "https://www.kakao.com/image1.jpg",
   "fileName": "image1.jpg",
   "width": 450,
   "height": 450,
   "size": 200000
 }

이미지 삭제하기

기본 정보
메서드 URL 인증 방식
DELETE https://api.keywordad.kakao.com/openapi/v1/images/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
- 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

이미지를 삭제합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청합니다. 삭제하려는 이미지의 ID를 파라미터로 지정해야 합니다. 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 이미지 ID O

예제

요청
curl -v -X DELETE "https://api.keywordad.kakao.com/openapi/v1/images/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8

더 보기

카카오 키워드광고> 이미지 관리