콘텐츠 API

콘텐츠 API는 SNS 게시물을 생성·예약하고, 이미지/동영상 미디어를 업로드하며, 발행 상태를 추적할 수 있는 엔드포인트를 제공합니다.

📌 엔드포인트 목록

메서드	경로	설명	필요 스코프
`POST`	`/v1/brand/contents/uploads`	미디어 파일(이미지/동영상) 업로드용 Presigned URL 발급	`publishing:create` 또는 `*`
`POST`	`/v1/brand/contents`	즉시 또는 예약 콘텐츠 발행 요청 (202 Accepted)	`publishing:create` 또는 `*`
`GET`	`/v1/brand/contents`	브랜드 콘텐츠 목록 조회 (페이징, 상태 필터)	`publishing:read` 또는 `*`
`GET`	`/v1/brand/contents/{content_id}`	특정 콘텐츠의 상세 정보 및 작업 상태 조회	`publishing:read` 또는 `*`
`DELETE`	`/v1/brand/contents/{content_id}/cancel`	대기 중인 예약 콘텐츠 발행 취소	`publishing:delete` 또는 `*`

1. 미디어 업로드 Presigned URL 발급 (`POST /v1/brand/contents/uploads`)

이미지나 동영상을 첨부하여 게시물을 발행하려면, 먼저 Presigned Upload URL을 발급받아 S3/R2 스토리지에 파일을 직접 업로드해야 합니다.

지원 미디어 규격

이미지 (최대 20MB, URL 유효시간 300초): image/jpeg, image/png, image/webp, image/gif
동영상 (최대 500MB, URL 유효시간 600초): video/mp4, video/quicktime (.mov), video/webm

요청 예시

curl -X POST "https://api.ankk.app/v1/brand/contents/uploads" \
  -H "Authorization: Bearer spk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "launch-banner.png",
    "content_type": "image/png",
    "size": 1420500
  }'

응답 예시 (`200 OK`)

{
  "upload_url": "https://storage.ankk.app/sns-posts/original/brand_.../launch-banner.png?X-Amz-Signature=...",
  "asset_ref": "https://cdn.ankk.app/sns-posts/original/brand_.../launch-banner.png",
  "method": "PUT",
  "object_key": "sns-posts/original/brand_.../launch-banner.png",
  "content_type": "image/png",
  "size": 1420500,
  "expires_in_seconds": 300
}

파일 바이너리 업로드 (PUT)

반환된 upload_url로 파일 바이너리를 PUT 방식으로 직접 업로드합니다:

curl -X PUT "<upload_url>" \
  -H "Content-Type: image/png" \
  --data-binary "@/path/to/launch-banner.png"

2. 콘텐츠 발행 요청 (`POST /v1/brand/contents`)

텍스트 본문과 앞서 업로드한 asset_ref를 전달하여 발행을 요청합니다.

요청 바디 필드

필드	타입	필수 여부	설명
`connection_id`	`string`	필수	대상 SNS 연결 계정 ID (연결 API에서 조회)
`idempotency_key`	`string`	필수	중복 발행 방지용 고유 키 (클라이언트가 생성)
`text`	`string`	선택	게시물 텍스트 본문
`media`	`array`	선택	첨부할 미디어 객체 배열 (`url` 또는 `asset_ref`)
`scheduled_for`	`string`	선택	예약 발행 시각 (ISO 8601 형식). 생략 시 즉시 발행
`thread_posts`	`array`	선택	Threads 스레드 작성 시 연결될 추가 게시물 목록
`provider_settings`	`object`	선택	플랫폼 전용 추가 설정 (예: 유튜브 카테고리 등)

즉시 발행 요청 예시

curl -X POST "https://api.ankk.app/v1/brand/contents" \
  -H "Authorization: Bearer spk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_01jm8x9k2example",
    "idempotency_key": "launch-2026-001",
    "text": "새로운 기능이 출시되었습니다! 🚀\nhttps://ankk.app",
    "media": [
      {
        "url": "https://cdn.ankk.app/sns-posts/original/brand_.../launch-banner.png"
      }
    ]
  }'

예약 발행 요청 예시

curl -X POST "https://api.ankk.app/v1/brand/contents" \
  -H "Authorization: Bearer spk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_01jm8x9k2example",
    "idempotency_key": "scheduled-launch-002",
    "scheduled_for": "2026-08-20T09:00:00Z",
    "text": "다음 주 월요일 오전 9시 예약 포스트입니다."
  }'

응답 예시 (`202 Accepted`)

{
  "content_id": "content_01jm8za2example",
  "status": "scheduled",
  "publish_job_id": "job_01jm8za2jobexample",
  "connection_id": "conn_01jm8x9k2example",
  "idempotency_key": "launch-2026-001"
}

3. 콘텐츠 목록 및 상태 조회

콘텐츠 목록 조회 (`GET /v1/brand/contents`)

curl -X GET "https://api.ankk.app/v1/brand/contents?status=published&limit=20" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

콘텐츠 단건 상세 조회 (`GET /v1/brand/contents/{content_id}`)

curl -X GET "https://api.ankk.app/v1/brand/contents/content_01jm8za2example" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

4. 예약 취소 (`DELETE /v1/brand/contents/{content_id}/cancel`)

아직 발행이 시작되지 않은 scheduled 상태의 콘텐츠를 취소합니다.

curl -X DELETE "https://api.ankk.app/v1/brand/contents/content_01jm8za2example/cancel" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

콘텐츠 API

📌 엔드포인트 목록

1. 미디어 업로드 Presigned URL 발급 (POST /v1/brand/contents/uploads)

지원 미디어 규격

요청 예시

응답 예시 (200 OK)

파일 바이너리 업로드 (PUT)

2. 콘텐츠 발행 요청 (POST /v1/brand/contents)

요청 바디 필드

즉시 발행 요청 예시

예약 발행 요청 예시

응답 예시 (202 Accepted)

3. 콘텐츠 목록 및 상태 조회

콘텐츠 목록 조회 (GET /v1/brand/contents)

콘텐츠 단건 상세 조회 (GET /v1/brand/contents/{content_id})

4. 예약 취소 (DELETE /v1/brand/contents/{content_id}/cancel)

🔗 관련 문서