Shortshock Open API

Base URL#

응답 형식과 에러 처리#

성공 응답:

{
  "success": true,
  "data": { ... }
}

실패 응답:

{
  "success": false,
  "message": "유효하지 않은 API 키입니다.",
  "statusCode": 401,
  "errorCode": null,
  "timestamp": "2026-08-24T09:00:00.000Z",
  "path": "/api/open-api/v1/projects"
}

message는 Accept-Language 헤더(ko 또는 en, 기본값 ko)에 따라 한국어 또는 영어로 내려갑니다.

Rate Limiting#

API 키 단위로 분당 요청 수 제한이 있습니다. 정확한 한도는 워크스페이스 구독 플랜에 따라 다릅니다. 한도를 초과하면 statusCode: 429와 함께 요청이 거부됩니다 — 이 경우도 HTTP 상태는 200이므로, 위 응답 형식대로 statusCode 필드를 확인해야 합니다.

핵심 개념#

채널, 내 콘텐츠, 프로젝트

프로젝트 미디어 타입

CAROUSEL의 최대 카드 수는 배포 대상 채널 중 가장 엄격한 값을 따릅니다 — Instagram 10장, TikTok 35장, Threads 20장, LinkedIn 20장, X 4장. TikTok·LinkedIn·X는 동영상 카드를 지원하지 않습니다. 제한을 넘으면 카드 추가·수정·배포 요청이 채널명과 함께 거절됩니다.

프로젝트 상태

채널별 배포 상태(items[].status)는 별도로 BEFORE_PUBLISHED, WAITING_TO_BE_ENQUEUED, PUBLISHING, SUCCEEDED, FAILED, THUMBNAL_FAILED, INACTIVATED_ITEM 값을 가집니다.

데이터 모델 규칙#

캡션과 제목은 반드시 common 하위에

update_project(PATCH /projects/:id)의 data 필드는 채널별 설정 객체(common, GoogleYoutube, Tiktok ...)로만 구성됩니다. 캡션과 제목은 반드시 아래 위치에 넣어야 합니다:

{
  "title": "프로젝트 이름",
  "isCommonMode": true,
  "data": {
    "common": {
      "description": "모든 채널에 공통으로 들어갈 캡션",
      "title": "YouTube 전용 제목 (다른 채널엔 적용 안 됨)"
    }
  }
}

isCommonMode: true일 때만 위 값이 채널별 아이템에 자동 전파됩니다. 채널마다 다른 캡션을 쓰려면 projectItemList를 직접 지정하세요 (이 경우 common 자동 전파는 건너뜁니다).

파일 업로드는 클라이언트가 직접 수행

create_video_project, create_article_project, add_carousel_card는 S3 presigned URL만 반환합니다. 실제 파일 바이트를 그 URL로 PUT하는 것은 호출한 클라이언트의 책임입니다 — 서버가 대신 업로드하지 않습니다. VIDEO 썸네일 업로드(POST /projects/:id/thumbnail)도 마찬가지입니다.

VIDEO 썸네일 변경

VIDEO 프로젝트의 썸네일은 두 가지 방법으로 바꿀 수 있으며, 어느 쪽이든 모든 채널에 같은 썸네일이 적용됩니다.

• 이미지 업로드 — POST /projects/:id/thumbnail에 contentType(예: image/jpeg)을 보내면 업로드용 uploadUrl과 fileKey를 반환합니다. 이미지를 그 URL로 PUT하면 처리 후 반영됩니다.
• 영상 속 장면 지정 — POST /projects/:id/thumbnail/timeline에 millisecond를 보내면 서버가 해당 위치의 프레임을 추출해 적용합니다. Instagram/TikTok 커버 위치도 같은 시점으로 설정되며, 영상 업로드가 끝난 뒤에만 가능합니다.

두 방법 모두 비동기로 처리됩니다. GET /projects/:id의 thumbnailKey가 응답의 fileKey와 같아지고 items[].thumbnailStatus가 COMPLETED가 되면 반영이 끝난 것입니다.

Quickstart — VIDEO 프로젝트 생성부터 배포까지#

1. 프로젝트 생성 (presigned URL 발급)

curl -X POST https://api.shortshock.net/api/open-api/v1/projects/video \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "여름 신제품 티저", "contentType": "video/mp4"}'

{
  "success": true,
  "data": { "projectId": 3476, "uploadUrl": "https://shortshock-media-prod.s3..." }
}

2. 파일 업로드 (S3에 직접 PUT)

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @teaser.mp4

3. 캡션/제목 설정

curl -X PATCH https://api.shortshock.net/api/open-api/v1/projects/3476 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "여름 신제품 티저",
    "isCommonMode": true,
    "data": { "common": { "description": "이번 여름, 새로운 시작 🌊", "title": "여름 신제품 티저 영상" } }
  }'

4. 상태 확인 (업로드/처리 완료 대기)

curl https://api.shortshock.net/api/open-api/v1/projects/3476 \
  -H "Authorization: Bearer $API_KEY"

status가 BEFORE_PROJECT_PUBLISHED가 되면 배포 가능한 상태입니다. 업로드된 미디어를 직접 확인하고 싶다면 응답의 mediaUrl(임시 조회용 URL)을 열어보세요.

5. 배포

curl -X POST https://api.shortshock.net/api/open-api/v1/projects/3476/publish \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

scheduledAt(ISO8601)을 넘기면 예약 배포, 생략하면 즉시 배포됩니다.

채널/콘텐츠 성과 조회#

메인 서비스의 채널 통계·내 콘텐츠 화면과 같은 데이터를 API로 조회할 수 있습니다. 통계 수치는 채널 갱신 시점 기준이므로, 최신 값이 필요하면 먼저 POST /connections/refresh로 갱신을 요청하고 GET /connections/refresh가 COMPLETED가 될 때까지 기다리세요.

팀 전체 채널 통계

curl "https://api.shortshock.net/api/open-api/v1/connections/statistics?period=ONE_WEEK" \
  -H "Authorization: Bearer $API_KEY"

period는 THREE_DAYS, ONE_WEEK, TWO_WEEKS, ONE_MONTH 중 하나입니다. 응답의 statistics.<플랫폼>에는 플랫폼 합계(total)와 계정별(accounts[]) 조회·좋아요· 댓글·공유 수가 현재 기간(current)과 직전 동일 기간(prev)으로 나뉘어 들어 있고, video.mostViewed / video.leastViewed에 기간 내 최다/최소 조회 콘텐츠가 들어 있습니다.

채널 상세와 채널 AI 분석

GET /connections/:connectionId는 채널 통계(channelInfo.followerCount 등), 카테고리/성향, 팔로워 성별·연령대 분포(audience), 가장 최근 채널 AI 분석 결과(analysis)를 반환합니다. 팔로워 추이는 GET /connections/:connectionId/statistics-timeseries로 조회합니다.

{
  "success": true,
  "data": {
    "connectionId": 12,
    "dataSourceName": "MetaInstagram",
    "name": "shortshock_official",
    "channelInfo": { "followerCount": 15230, "followingCount": 210, "mediaCount": 342 },
    "categories": [{ "id": 3, "name": "뷰티", "isPrimary": true }],
    "tones": [{ "id": 7, "name": "유쾌한" }],
    "audience": { "valueType": "count", "age": [...], "gender": [...] },
    "analysis": {
      "status": "COMPLETED",
      "progress": null,
      "summary": "...",
      "collaborationPoints": [{ "title": "...", "description": "..." }],
      "requestedAt": "2026-09-20T03:00:00.000Z"
    }
  }
}

analysis가 null이면 분석 이력이 없는 것이고, analysis.status가 COMPLETED가 아니면 분석이 진행 중이거나 실패한 상태입니다.

내 콘텐츠 목록과 상세

curl "https://api.shortshock.net/api/open-api/v1/contents?limit=20&connectionIdList=12" \
  -H "Authorization: Bearer $API_KEY"

각 아이템의 meta에 통계치(viewCount, likeCount, commentCount, shareCount)가 들어 있습니다. 기간(startAt/endAt, 게시일 기준, 기본 최근 7일) 필터를 지원하며, limit을 넘기면 응답의 nextCursor를 다음 요청의 cursor로 넘겨 페이지를 이어 조회합니다.

GET /contents/:contentId는 같은 필드에 AI 분석 결과 전문(analysis)을 더해 반환합니다 — analysis.summary(요약·특징·개선 피드백·구간별 타임라인), analysis.pattern(주제 카테고리, 콘텐츠 목적, 훅 유형, 편집/오디오/자막/톤앤매너 수치). 분석 전이면 각 항목이 null입니다.

엔드포인트 개요#

전체 요청/응답 스키마는 API Reference에서 확인하세요.

다음 단계#

Claude 등 AI 에이전트에서 이 API를 도구(tool) 형태로 바로 쓰고 싶다면 MCP 연동 가이드를 참고하세요.