본문으로 건너뛰기

📰 뉴스 피딩 가이드

개요​

카카오의 뉴스 콘텐츠(이하 콘텐츠)의 API 연동 설정을 위한 가이드 문서입니다. API를 통해 콘텐츠를 생성, 수정, 삭제 및 조회하는 방법을 설명합니다.

또한 기존 전송 방식과의 차이점, 인증 방법, API 호출 예제 등을 포함하고 있습니다.

기존 FTP 송고와의 차이점​

FTP를 이용한 콘텐츠 전송은 오랫동안 안정적으로 사용되어 온 시스템이지만 전송 시에 보안에 취약하고, 신규 기능 확장에 문제가 있었습니다. API 연동을 통해 아래와 같은 이점을 얻을 수 있습니다.

  • HTTPS 및 API Key 방식 도입에 따른 보안성 강화
  • 자동 송고로 처리할 수 있는 다양한 신규 기능 도입

API 공통사항​

  • API 호출시엔 반드시 API Key 를 요청 헤더에 포함시켜야 합니다.
  • API는 테스트 전송을 위한 환경과 실제 콘텐츠 전송을 위한 환경이 별도로 구성되어있습니다. 각각의 API Key를 사용하여 환경에 따라 송고 방식(테스트 전송 / 운영 환경 전송)이 결정됩니다.
  • 모든 API는 UTF-8 인코딩으로 요청과 응답을 처리합니다. EUC-KR 등 다른 문자 인코딩은 더 이상 지원하지 않습니다.

URL​

모든 API 호출 시에 아래의 URL + API 별 Path를 지정하여 API를 사용하게 됩니다.

운영 환경 URLhttps://gate-partners.harmony.kakao.com
테스트 환경 URLhttps://gate-partners-test.harmony.kakao.com

API 인증​

인증 방식​

사용자를 식별하기 위하여 HTTP header 를 이용한 기본 인증(Basic Authentication) 방식으로 인증합니다. ID 가 test 이고 API 키가 key 인 경우 test:key 를 Base64 방식으로 인코딩하여 아래와 같이 Authorization 헤더 값에 포함하여 API 를 요청해야 합니다.

Authorization: Basic dGVzdDprZXk=

API 키 발급 & 권한​

담당자 승인 후, 키를 발급하고 사용할 서비스 API 에 맞는 권한을 별도로 부여합니다.

주의

ID 와 API 키는 담당자 승인 후 발급됩니다. 파트너 별로 관리되는 값이므로 유출되지 않도록 보안에 주의하시기 바랍니다. 키를 분실한 경우 담당자 확인 후 재발급 받을 수 있습니다.

인증 테스트​

테스트 URL​

https://gate-partners-test.harmony.kakao.com/feed/api/check/auth

curl 사용 예시​

id 가 test 이고 api 키가 key 인 경우 아래와 같이 Authorization 헤더에 포함하여 API 를 요청합니다.

curl --location --include \
-u test:key \
--request GET \
'https://gate-partners-test.harmony.kakao.com/feed/api/check/auth'
curl --location --include \
--header 'Authorization: Basic dGVzdDprZXk=' \
--request POST \
'https://gate-partners-test.harmony.kakao.com/feed/api/check/auth'

인증 API 응답​

HTTP/2 200 OK
content-type: application/json

{
  "result": "OK",
  "username": "test",
  "checkDt": "2024-12-31T23:59:59.999+09:00"
}

API 목록​

기능API endpoint
콘텐츠 생성/수정POST /api/v1/contents/feed
콘텐츠 생성/수정 (미디어 파일)POST /api/v1/contents/feed/file
콘텐츠 삭제 (uuid)DELETE /api/v1/contents/feed/uuid/{uuid}
콘텐츠 삭제 (content id)DELETE /api/v1/contents/feed/content-id/{content id}
결과 조회 (uuid)GET /api/v1/contents/feed/uuid/{uuid}
결과 조회 (content id)GET /api/v1/contents/feed/content-id/{content id}
결과 미리보기GET /api/v1/contents/feed/preview/{uuid}

콘텐츠 신규 생성 / 수정​

다음 서비스 영역에 노출될 콘텐츠를 전송합니다.

POST /api/v1/contents/feed

본문 파라미터​

이름유형필수 여부포맷 및 제한설명
contentId문자열필수최대 500자제휴사에서 지정한 콘텐츠별 ID
title문자열필수최대 500자콘텐츠 제목
subtitle문자열선택최대 500자콘텐츠 부제목
categories문자열 배열선택콘텐츠의 카테고리 정보 배열. 배열의 첫 번째를 대표 카테고리로 지정
linksobject선택콘텐츠의 외부 URL 정보 배열
writersarray1개 이상 필수콘텐츠 작성자 정보 배열
bodyHtml문자열필수표준 HTML 포맷 기반의 콘텐츠 본문 정보
createdDateDatetime필수yyyy-MM-dd'T'HH:mm:ss.SSSXXX콘텐츠의 생성 시간 (예시: 2024-04-01T13:00:00.000+09:00)
modifiedDateDatetime선택yyyy-MM-dd'T'HH:mm:ss.SSSXXX콘텐츠의 수정 시간 (예시: 2024-04-01T13:00:00.000+09:00)
enableCommentBoolean선택콘텐츠의 댓글(타임톡) 사용 여부를 지정할 수 있는 기능. 별도 설정하지 않을 시 매체 설정을 따릅니다.
true : 댓글(타임톡) 사용
false : 댓글(타임톡) 미사용(OFF)
이름유형필수 여부포맷 및 제한설명
externalobject선택원본 콘텐츠 URL 정보
relatedarray선택최대 10개관련 콘텐츠 URL 정보 배열

External 정보​

이름유형필수 여부포맷 및 제한설명
url문자열필수원본 콘텐츠 URL 정보
pcUrl문자열선택원본 콘텐츠 URL 정보. PC와 Mobile 페이지의 URL 이 다른 경우에만 사용합니다.
mobileUrl문자열선택원본 콘텐츠 URL 정보. PC와 Mobile 페이지의 URL 이 다른 경우에만 사용합니다.
이름유형필수 여부포맷 및 제한설명
title문자열필수최대 500자관련 콘텐츠 제목
url문자열필수관련 콘텐츠 URL 정보

Writer 정보​

이름유형필수 여부포맷 및 제한설명
name문자열필수최대 100자콘텐츠 작성자 이름 혹은 닉네임
email문자열필수이메일 형식 / 최대 100자콘텐츠 작성자의 E-mail 정보 (혹은 공용 이메일)

HTTP sample​

curl --request POST "https://gate-partners-test.harmony.kakao.com/api/v1/contents/feed" \
--header "Content-Type: application/json" \
--header "Authorization: {Basic Authentication}" \
--data '{
  "contentId": "TEST-00001",
  "title": "제목은 \"필수\"값 입니다",
  "subtitle": "부제목",
  "categories": [
    "car",
    "food"
  ],
  "links": {
    "external": {
      "url": "https://kakao.com/article/1"
    },
    "related": [
      {
        "title": "항생제 내성 '슈퍼버그'…약 대신 파지 칵테일 '김치'로 잡는다",
        "url": "https://v.daum.net/v/20241128190147720"
      },
      {
        "title": "CG인바이츠 “조중명 전 대표, 1400억원 규모 손배소 제기”",
        "url": "https://v.daum.net/v/20241128192923377"
      }
    ]
  },
  "writers": [
    {
      "name": "라이언",
      "email": "ryan@kakao.com"
    },
    {
      "name": "조르디",
      "email": "jordy@kakao.com"
    }
  ],
  "bodyHtml": "<p><strong>문단1</strong></p><p>문단2<p/>",
  "createdDate": "2024-11-27T14:00:00.000+09:00",
  "modifiedDate": "2024-11-27T14:13:33.387+09:00",
  "enableComment": false
}'

콘텐츠 신규 생성 / 수정 (미디어 파일)​

콘텐츠와 본문에 포함된 미디어 파일을 업로드하는 경우 본문과 함께 전송합니다.

POST /api/v1/contents/feed/file

전송 파일 정보​

이름파일 확장자파일 종류
requestjson콘텐츠 신규 생성/수정의 본문 파라미터와 동일한 포맷의 JSON 파일
files이미지, 동영상(mp4) 확장자콘텐츠 본문 내에 삽입 된 이미지, 동영상 파일

HTTP sample​

curl --request POST "https://gate-partners-test.harmony.kakao.com/api/v1/contents/feed/file" \
--header "Authorization: {Basic Authentication}" \
--header "Content-Type: multipart/form-data" \
--form 'request={
  "contentId": "TEST-00002",
  "title": "제목은 \"필수\"값 입니다",
  "subtitle": "부제목",
  "categories": [
    "car",
    "food"
  ],
  "links": {
    "external": {
      "url": "https://kakao.com/article/1",
      "pcUrl": "https://kakao.com/article/1",
      "mobileUrl": "https://kakao.com/article/1"
    },
    "related": [
      {
        "title": "항생제 내성 '슈퍼버그'…약 대신 파지 칵테일 '김치'로 잡는다",
        "url": "https://v.daum.net/v/20241128190147720"
      },
      {
        "title": "CG인바이츠 “조중명 전 대표, 1400억원 규모 손배소 제기”",
        "url": "https://v.daum.net/v/20241128192923377"
      }
    ]
  },
  "writers": [
    {
      "name": "라이언",
      "email": "ryan@kakao.com"
    },
    {
      "name": "조르디",
      "email": "jordy@kakao.com"
    }
  ],
  "bodyHtml": "<p><strong>문단1</strong></p><p>문단2<p/><img src=\"sample.jpg\" alt=\"이미지 캡션\" /><p>문단3<p/>",
  "createdDate": "2024-11-27T14:00:00.000+09:00",
  "modifiedDate": "2024-11-27T14:13:33.387+09:00",
  "enableComment": false
};type=application/json' \
--form 'files=@sample.jpg;type=image/jpeg'

콘텐츠 생성/수정 응답​

응답 포맷​

이름유형NULL 가능설명
contentId문자열아니오제휴사에서 지정한 콘텐츠 ID
uuid문자열아니오시스템에서 발급된 고유 처리 ID
status문자열아니오파일 처리 상태
createdDate날짜아니오콘텐츠 생성 날짜
errorMessage문자열예(에러 발생시) 에러에 관한 세부 설명
{
  "contentId": "{제휴사의 콘텐츠 ID}",
  "uuid": "{시스템에서 발급된 콘텐츠 ID}",
  "status": "READY",
  "createdDate": "2025-01-01T00:00:00.000+09:00",
  "errorMessage": null
}

콘텐츠 삭제 (uuid)​

생성/수정 API 에서 응답되는 uuid 로 콘텐츠 삭제합니다.

DELETE /api/v1/contents/feed/uuid/{uuid}

Path 파라미터​

이름유형필수 여부포맷 및 제한설명
uuid문자열필수10글자 길이의 정해진 고유 ID콘텐츠 생성 및 수정 결과에서 반환되는 처리 ID

콘텐츠 삭제 (content id)​

생성/수정시 사용한 content id 로 콘텐츠를 삭제합니다.

DELETE /api/v1/contents/feed/content-id/{contentId}

Path 파라미터​

이름유형필수 여부포맷 및 제한설명
contentId문자열필수최대 500자제휴사에서 지정한 콘텐츠 별 ID

콘텐츠 삭제 응답​

응답 포맷​

HTTP/2 200 OK

결과 조회 (uuid)​

생성/수정 API 에서 응답되는 uuid 로 결과 조회

 GET /api/v1/contents/feed/uuid/{uuid}

Path 파라미터​

이름유형필수 여부포맷 및 제한설명
uuid문자열필수10글자 길이의 정해진 고유 ID콘텐츠 생성 및 수정 결과에서 반환되는 처리 ID

결과 조회 (content id)​

생성/수정시 사용한 content id 로 결과 조회

GET /api/v1/contents/feed/content-id/{contentId}

Path 파라미터​

이름유형필수 여부포맷 및 제한설명
contentId문자열필수최대 500자제휴사에서 지정한 콘텐츠별 ID

결과 조회 응답​

응답 포맷​

이름유형NULL 가능설명
contentId문자열아니오제휴사에서 지정한 콘텐츠 ID
uuid문자열아니오시스템에서 발급된 고유 처리 ID
status문자열아니오파일 처리 상태
errorMessage문자열예(에러 발생시) 에러에 관한 세부 설명
createdDate날짜아니오콘텐츠 생성 날짜
previewUrl문자열예콘텐츠 미리보기 URL 경로
 {
  "contentId": "{제휴사에서 지정한 콘텐츠 ID}",
  "uuid": "{시스템에서 발급된 고유 처리 ID}",
  "status": "SUCCESS",
  "errorMessage": null,
  "createdDate": "2025-01-01T00:00:00.000+09:00",
  "previewUrl": "/api/v1/contents/feed/preview/{uuid}"
}

Status 객체 정보​

상태설명
SUCCESS콘텐츠가 정상적으로 처리 완료 된 상태
ERROR콘텐츠가 일시적으로 처리 실패 된 상태. 일시적인 문제일 수 있으므로 1분 후 다시 처리를 시도합니다.
FAIL콘텐츠 처리 실패 상태. ERROR 상태에서 수차례 실패가 반복되거나, 콘텐츠 포맷에 문제가 있는 경우 FAIL 상태가 됩니다.
READY콘텐츠 처리 대기 상태. 아직 처리를 시작하지 않은 상태입니다.
PROCESSING콘텐츠 처리 중 상태

피딩 결과 미리보기​

테스트 피딩의 결과 미리보기 제공

GET /api/v1/contents/feed/preview/{uuid}

응답​

참고

💡 HTML 포맷으로 응답 되며, 실제 서비스 화면과는 차이가 있을 수 있습니다.

<head></head><h1>테스트 예시</h1>
<body>
<section dmcf-sid="uypSioYcEU"><p dmcf-pid="7lAP5Fe7Ip" dmcf-ptype="general">안녕하세요!</p>
    <p dmcf-pid="zIa4H5xpI0" dmcf-ptype="general">안녕하세요123</p>
    <p dmcf-pid="qCN8X1MUm3" dmcf-ptype="general">안녕하세요!<br/>테스트중</p>
    <figure dmcf-pid="BFSNKVEQwF" dmcf-ptype="figure"><img dmcf-mid="0vqUOhBWsz" dmcf-mtype="image" height="500"
                                                           src="https://t1-sandbox.kakaocdn.net/news/202405/13/jade_test/20240513150859430xsgi.png"
                                                           width="500"/></figure>
    <p dmcf-pid="b3vj9fDxst" dmcf-ptype="general">안녕하세요!</p>
    <div dmcf-pid="KyDR3UnbO1" dmcf-ptype="general">
        <iframe allowfullscreen="allowfullscreen" dmcf-mid="pGoVYXP3O7" dmcf-mtype="video/youtube" frameborder="0"
                height="315" scrolling="no" src="https://www.youtube.com/embed/3y8KUpSm4zo" width="560">Your browser
            does not support iframes.
        </iframe>
    </div>
    <p dmcf-pid="9Wwe0uLKO5" dmcf-ptype="general">테스트중</p></section>
</body>

콘텐츠 본문​

표준 HTML 지원​

이곳은 본문이며,<br>
표준 <strong>HTML</strong> 태그를 지원합니다.

카카오 정책에 따른 스타일(style)이 적용됩니다.
<p>본문은 여러 문단으로 분리할 수 있습니다.</p>
<br><br>
<p>문단을 분리할 수 있는 기본적인 방법은 p 태그로 감싸거나 br 태그 2개를 사용하면 됩니다.</p>

이곳은 본문이며,<br>
표준 <strong>HTML</strong> 태그를 지원합니다.

<img src="http://domain.com/image.jpg" alt="이미지 캡션" />

카카오 정책에 따른 스타일(style)이 적용됩니다.

<p>본문은 여러 문단으로 분리할 수 있습니다.</p><br>
문단을 분리할 수 있는

<p>기본적인 방법은 p 태그로 감싸거나</p> br 태그 2개를 사용하면

<br><br> 됩니다.

제공되는 문단 형식​

  • 가로선 <hr>

    카카오의 블록체인 기술 계열사 그라운드X는 디지털 자산 모바일 지갑 서비스 '클립'을 출시했다고 3일 밝혔다.
    <hr>
    클립 사용자는 소셜·게임·쇼핑 등 클레이튼 기반 블록체인 애플리케이션(비앱)에서 얻은 디지털 자산을 보관하거나 카카오톡 친구에게 보낼 수 있다.
    현재 '클레이'를 포함한 총 11종의 가상자산을 지원한다.

  • 라인쿼트 <blockquote dmcf-ptype="blockquote2">

    <blockquote dmcf-ptype="blockquote2">카카오의 블록체인 기술 계열사 그라운드X는 디지털 자산 모바일 지갑 서비스 '클립'을 출시했다고 3일 밝혔다.</blockquote>

  • 큰 제목 <h3>

    <h3>카카오의 블록체인 기술 계열사 그라운드X는 디지털 자산 모바일 지갑 서비스 '클립'을 출시했다고 3일 밝혔다.</h3>
    클립 사용자는 소셜·게임·쇼핑 등 클레이튼 기반 블록체인 애플리케이션(비앱)에서 얻은 디지털 자산을 보관하거나 카카오톡 친구에게 보낼 수 있다.
    현재 '클레이'를 포함한 총 11종의 가상자산을 지원한다.

  • 쿼트 <blockquote dmcf-ptype="blockquote1">

    <blockquote dmcf-ptype="blockquote1">카카오의 블록체인 기술 계열사 그라운드X는 디지털 자산 모바일 지갑 서비스 '클립'을 출시했다고 3일 밝혔다.</blockquote>

  • 블록쿼트 <blockquote dmcf-ptype="pre">

    <blockquote dmcf-ptype="pre">카카오의 블록체인 기술 계열사 그라운드X는 디지털 자산 모바일 지갑 서비스 '클립'을 출시했다고 3일 밝혔다. 클립 사용자는 소셜·게임·쇼핑 등 클레이튼 기반 블록체인 애플리케이션(비앱)에서 얻은 디지털 자산을 보관하거나 카카오톡 친구에게 보낼 수 있다.
    현재 '클레이'를 포함한 총 11종의 가상자산을 지원한다.</blockquote>

이미지 / 동영상 첨부​

이미지​

<img> 태그를 사용하여 본문에 이미지를 추가 합니다. 모든 외부 이미지는 카카오의 이미지 서버에 업로드 되고 카카오 서비스에 맞춰 크기가 조절됩니다.

  • img 태그 속성

    속성설명
    src이미지 원본 주소 or 업로드 파일명 or data URI
    alt이미지 캡션
    data-thumbnailtrue 인 경우 대표 이미지로 지정됩니다. 없으면 첫번째 이미지를 대표 이미지로 사용합니다.

  • 이미지 파일 크기와 비율

    속성설명
    최소 크기100 x 100
    최대 용량30 MB
    지원 확장자jpg, gif, png
    비율본문 내 이미지는 비율은 유지한 채 리사이징 됩니다.
참고

예를 들어 본문의 고정 가로길이가 700인 경우 각 크기의 원본 이미지는 아래와 같이 리사이징 되어 보여집니다.

  • 300x200 -> 300x200 (작은 이미지)
  • 1000x800 -> 700x560 (큰 이미지)
  • 300x800 -> 300x800 (작은 세로 이미지)
  • 1000x3000 -> 700x2100 (큰 세로 이미지)
  • html sample 
    <!-- 이미지 원본 주소(권장) -->
    <img src="https://t1.kakaocdn.net/kakaocorp/kakaocorp/service/main/img_ryan.png" alt="이미지1" />

    <!-- 업로드한 이미지 파일명-->
    <img src="sample.jpg" alt="이미지2" data-thumbnail="true" />

    <!-- dataURI -->
    <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" alt="이미지3" />

동영상​

  1. 원본 동영상을 전송하여 서비스하는 경우 (권장) <video> 태그를 사용하여 본문의 원하는 위치에 동영상을 추가 합니다. 파일은 연결된 카카오TV 채널로 업로드 되고 인코딩 됩니다.

    참고

    원본 동영상을 전송파일에 업로드하는 경우에는 사전에 카카오TV 업로드를 위한 협의가 필요합니다.

    카카오TV 업로드 협의를 위해서는 아래 내용을 제휴 담당자에게 전달해 주세요.

    1. 카카오TV의 카카오 계정
    2. 업로드할 카카오TV의 채널 URL (예시,https://tv.kakao.com/channel/2653214)
    3. 광고 차단 여부 : 광고를 차단하면 해당 카카오TV 채널에 업로드된 동영상에는 광고가 노출되지 않습니다.

    video 태그 속성

    속성설명
    src업로드된 영상 파일의 파일명
    poster썸네일로 사용할 이미지 원본 주소 혹은 파일명. 없으면 자동으로 설정됩니다.

    동영상 파일 제한

    속성설명
    최대 용량2 GB
    지원 확장자카카오TV에서 지원하는 AVI, WMV, ASF, MPEG, MOV, DV, QT 동영상 파일을 지원합니다.

    이 중에서 MPEG4 계열의 Xvid나 Divx 코덱을 사용한 AVI 파일이 인코딩하여 가장 좋은 결과물을 얻을 수 있는 파일입니다. |

    html sample

    <!-- 썸네일 이미지 원본 주소 -->
    <video src="sample.mp4" poster="https://t1.kakaocdn.net/kakaocorp/kakaocorp/service/main/img_ryan.png" />

    <!-- 썸네일 이미지를 함께 전송한 경우 -->
    <video src="sample.mp4" poster="sample.jpg" />

  2. 본문에 iframe 태그로 삽입된 플레이어 지원 카카오TV, YouTube 만 지원합니다.

    html sample

    <iframe src="https://www.youtube.com/watch?v=pyg5BWzpy5Y" />

FAQ 💡​

이미지 직접 첨부와 원본 주소 삽입의 차이는 무엇인가요?​

직접 첨부한 파일이나 링크로 삽입된 파일 모두 별도로 업로드하여 제공하기 때문에, 전송 방식만 다를 뿐 콘텐츠 결과는 같게 됩니다.

이미지는 어떤 방식으로 처리 되나요?​

콘텐츠 내 모든 사진 & 동영상은 모두 별도의 카카오 서버로 업로드 되어 서비스 됩니다.

이미지 원본 주소 삽입 방식의 경우 카카오 서버에서 접근 가능한 주소여야 정상적으로 처리됩니다.

카테고리를 잘못 보내거나 안보내면 어떻게 되나요?​

적절한 카테고리를 찾지 못하는 경우, 카테고리가 없는 상태로 발행됩니다.

전송된 원본 콘텐츠의 모습(font color와 같은 style)과 카카오에서 서비스되는 모습이 왜 다른가요?​

각기 다른 매체의 본문 style을 그대로 채용할 경우에는 저희 서비스의 UI 깨짐이나 너무 다른 Font 컬러, 굵기등이 그대로 노출될 가능성이 있습니다.

이렇게 되면, 저희 서비스 품질이 저하되는 문제가 발생되기 때문에, 내부적으로 허용되는 HTML tag들이 존재합니다.

따라서 다르게 보이는 경우가 발생하게 됩니다. 하지만 대부분의 경우 만족할 만한 UI를 보이게 되니 너무 걱정하지 않으셔도 됩니다.

콘텐츠 수정을 다음채널 스튜디오 에디터에서 해도 반영 되나요?​

API를 통해 문서 수정을 한 동시에 다음채널 스튜디오 에디터에서 다시 수정하는 행위는 삼가 부탁드립니다. 자동피딩에서의 수정과 에디터에서의 수정 내용이 서로 충돌 할 수 있습니다. 문서의 수정은 피딩을 통해서 진행 부탁드립니다.