개발자 API
1. 한눈에 보기
내 프로그램에서 영상을 YouTube 채널에 예약 업로드하고(1~8장), 같은 영상과 사진을 SNS 계정(Instagram·Facebook·Threads·TikTok)에도 게시·예약하는(9~11장) API입니다. YouTube 업로드 순서는 세 단계입니다.
- 파일 올리기: 영상(필요하면 썸네일)을 이 서비스에 올립니다. 큰 파일은 조각(청크)으로 나눠 올리고, 끊기면 이어서 올립니다.
- 예약 만들기: 올린 파일 id, 제목·설명, 공개 범위, 업로드 시각을 담은 매니페스트(JSON)를 보냅니다.
- 상태 확인: 예약 시각이 되면 서비스가 YouTube에 올립니다. 작업 상태나 이벤트 목록으로 결과(
video_id)를 받습니다.
모든 요청과 응답은 JSON(UTF-8)이고, 시각은 시간대가 붙은 ISO-8601(예: 2026-10-20T09:00:00Z, 2026-10-20T18:00:00+09:00)입니다. 서버는 UTC로 저장하고 UTC로 돌려줍니다.
먼저 웹에서 채널과 SNS 계정을 연결해 두어야 합니다. API로는 계정을 연결할 수 없습니다. 이 문서의 모든 요청은 https로 보냅니다.
2. 인증과 토큰
API 토큰 화면에서 토큰을 만들고 모든 요청에 헤더로 붙입니다.
Authorization: Bearer ust_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- 토큰 원문은 만들 때 한 번만 보입니다. 잃어버리면 회수하고 새로 만드세요.
- 유효 기간은 기본 90일, 최대 365일입니다. 계정당 살아 있는 토큰은 20개까지입니다.
- 토큰은 만든 사람의 계정과 그 계정이 연결한 채널에만 쓸 수 있습니다.
- 토큰을 코드나 저장소에 넣지 말고 환경변수 등 비밀 저장소에 두세요.
권한(scope)
| 권한 | 할 수 있는 일 |
|---|---|
uploads:write | 파일 올리기(/uploads) |
jobs:read | 예약·이벤트·연결 채널 목록 보기 |
jobs:write | 예약 만들기·취소 |
jobs:publish | 일부공개·공개·예약 공개 예약을 웹 확인 없이 바로 대기열에 넣기(jobs:write와 함께 체크) |
analytics:read | 채널 개요·최근 영상·통계 읽기 |
social:read | SNS 계정 목록, 게시 상태·성과, 카드 조회, 예약 일정의 SNS 줄, 그룹의 SNS 구성원 읽기(9장) |
social:write | SNS 게시·예약·취소, 사진 게시(카드) 만들기, POST /jobs의 social 필드 쓰기(9장·10장) |
egress:read | 내게 배정된 업로드 IP·채널별 선택 읽기(8-1). 예전 토큰은 jobs:read로도 됩니다 |
egress:write | 채널별 업로드 IP 바꾸기(8-1). jobs:write로는 안 됩니다(읽기와 달리 호환 없음) |
SNS 게시를 만든 뒤 상태까지 보려면 social:write와 social:read를 함께 체크하세요. 쓰기 권한이 읽기를 포함하지 않습니다.
권한이 없는 요청은 403 insufficient_scope, 토큰이 틀리거나 만료·회수됐으면 401 unauthorized입니다.
3. 공개 범위
매니페스트의 visibility.target으로 정합니다.
| 값 | 뜻 |
|---|---|
private | 비공개(기본값) |
unlisted | 일부공개(링크가 있는 사람만) |
public | 공개 |
scheduled | 예약 공개. 비공개로 올린 뒤 visibility.publish_at에 YouTube가 공개로 바꿉니다. |
저작권 신호 확인 뒤 승인 공개·간격 공개 (publish_gate)
visibility.target이 public·unlisted·scheduled이면 기본으로 먼저 비공개로 올리고(scheduled여도 YouTube publishAt은 보내지 않습니다), 서비스가 YouTube API 신호를 확인한 뒤 공개합니다. 선택 칸 visibility.publish_gate: "auto"(기본, 서버 설정 publish_gate_default) 또는 "off"(예전처럼 바로 올림). "off"는 웹 폼에서만 쓸 수 있고, API 요청의 "off"는 jobs:publish 권한이 있어도 "auto"로 처리되며 응답 warnings에 PUBLISH_GATE_OFF_IGNORED가 붙습니다. private는 게이트 없이 그대로 비공개입니다. 공개 허용 전(위의 강제 비공개)에 만든 예약도 게이트를 갖습니다: 업로드는 지금처럼 강제 비공개이고, 공개는 공개 허용이 켜진 뒤 확인을 거쳐서만 됩니다(꺼져 있는 동안은 기다릴 뿐 멈추지 않습니다). 입력 검증, 웹 확인(awaiting_web_confirm), jobs:publish 판단은 요청한 값 기준으로 이전과 똑같습니다.
- 업로드 완료 10분 뒤 첫 확인, 그 뒤 1시간마다(
publish_gate_check_minutes)videos.list(status·contentDetails·processingDetails)로 신호를 읽습니다. 공개 직전에는 반드시 한 번 더 새로 읽습니다. - 막는 신호:
uploadStatus가rejected·failed·deleted,rejectionReason(claim·copyright·legal·trademark·duplicate 등),regionRestriction, 요청에 없던embeddable=false. 하나라도 있으면 즉시blocked이고 비공개로 둡니다. 처리 중이면 기다립니다. 연령 제한(ytAgeRestricted)은 기록만 하고 막지 않습니다. - 공개 조건: 신호 없음 확인이 2회 이상 쌓여
ready(공개 후보)가 되고, 공개 시각(요청한publish_at, 없으면 업로드 완료 1시간 뒤)이 지났고, 사람이 승인했거나 그 채널이 사람이 켠 «n시간 간격 공개» 일 때, 방금 새로 읽은 값이private일 때만 공개합니다. 문제가 없어도 자동으로 공개하지 않습니다(기본은 승인 후 공개). 확인 횟수가 모자라면 다음 주기로 미루므로 공개가 예약보다 늦어질 수 있습니다. - 한계: 일반 채널은 자기 영상의 Content ID 클레임을 API로 읽을 수 없습니다(
claimSearch는 CMS 파트너 전용). 수익 창출·추적형 클레임은 신호로 나오지 않을 수 있어, 응답의 이름도 «저작권 문제 없음»이 아니라 «API 저작권 신호 없음»입니다. 스튜디오 내부 API나 쿠키는 쓰지 않습니다. - 클라이언트 주의: 게이트가 있는 작업은
state: "uploaded"여도publish_gate.state가published가 되기 전까지 YouTube에서는 비공개입니다.
웹 확인과 jobs:publish
토큰에 jobs:publish가 없으면, 비공개가 아닌 예약은 상태가 awaiting_web_confirm으로 만들어지고 올라가지 않습니다. 계정 주인이 웹의 예약 목록에서 “확인”을 눌러야 대기열(queued)로 넘어갑니다. 토큰이 새거나 스크립트가 잘못 돌아도 영상이 갑자기 공개되지 않게 하는 장치입니다.
사람 확인 없이 완전히 자동으로 공개하려면 토큰을 만들 때 “일부공개·공개 바로 게시 (jobs:publish)”를 체크하세요. 그 토큰으로 만든 예약은 바로 queued가 됩니다. 이 권한이 있는 토큰은 특히 조심해서 보관하세요.
아래 기기 승인으로 받은 토큰에는 승인 화면의 “바로 올리기” 체크박스(기본 체크)가 켜져 있으면 jobs:publish가 들어갑니다(끄면 빠집니다). 나중에 웹 “API 토큰” 화면에서 그 기기 토큰의 바로 공개를 켜고 끌 수도 있습니다.
4. 1단계: 파일 올리기
4-1. 자리 열기
POST /api/v1/uploads
Content-Type: application/json
{"kind": "video", "content_type": "video/mp4", "size": 734003200,
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}
kind:video,thumbnail,caption(자막 SRT·VTT) 또는image(SNS 사진 게시용, 10장)content_type: 영상video/mp4·video/quicktime·video/webm, 썸네일image/jpeg·image/png, 사진(image)image/jpeg만size: 파일 전체 바이트 수. 영상 최대 20 GiB, 썸네일 최대 50 MiB(YouTube 썸네일 자체 한도는 2 MB이니 그 아래로), 사진 최대 4 MiBsha256: 파일 전체의 SHA-256(소문자 16진수 64자). 필수입니다.
응답 201:
{"upload_id": "up_0123456789abcdef01234567", "kind": "video", "content_type": "video/mp4",
"size": 734003200, "offset": 0, "state": "pending", "sha256": "e3b0…b855", "error_code": null,
"created_at": "…", "received_at": null, "deleted": false,
"chunk_size": 16777216, "max_chunk_size": 67108864}
4-2. 조각 보내기
PUT /api/v1/uploads/{upload_id}
Content-Range: bytes 0-16777215/734003200
Content-Length: 16777216
(파일의 0~16777215 바이트)
- 조각 크기는
chunk_size(16 MiB)를 권장하고, 최대max_chunk_size(64 MiB)입니다. 64 MiB 이하 파일은 한 번에 보내도 됩니다. Content-Range의 끝 값은 포함 범위입니다(bytes 시작-끝/전체). 시작 값은 지금까지 받은 바이트 수(offset)와 정확히 같아야 합니다.- 응답:
{"upload_id": "…", "offset": 16777216, "state": "receiving", "error_code": null, "verifying": false} - 시작 값이 어긋나면
409 offset_mismatch와 함께 서버가 가진offset을 돌려줍니다. 그 값부터 다시 보내면 됩니다. - 끊겼을 때는
HEAD /api/v1/uploads/{upload_id}의Upload-Offset헤더(또는GET의offset)에서 이어 보내세요. - 첫 조각의 첫머리가 선언한 형식(mp4·mov·webm·jpg·png)과 다르면
415 magic_mismatch로 거절됩니다.
4-3. 확인 기다리기
마지막 조각을 받으면 서버가 SHA-256과 형식을 다시 확인합니다. 256 MiB 이하는 마지막 PUT 응답에서 바로 "state": "received"가 오고, 더 큰 파일은 "verifying": true가 온 뒤 뒤에서 확인합니다. GET /api/v1/uploads/{upload_id}를 몇 초 간격으로 불러 state가 received가 되면 다음 단계로 가세요.
| state | 뜻 |
|---|---|
pending | 자리만 열림(첫 바이트 전). 1시간 안에 아무것도 안 오면 닫힙니다. |
receiving | 받는 중 또는 확인 중. 24시간 동안 조각이 안 오면 버려집니다. |
received | 다 받고 확인 끝. 예약에 쓸 수 있습니다. |
failed | 실패. error_code: SHA256_MISMATCH, SIZE_MISMATCH, MAGIC_MISMATCH, DISK_ERROR, ABANDONED 등 |
예약에 쓰이지 않은 파일은 48시간 뒤, 업로드가 끝난 파일은 끝난 뒤 지웁니다. 올린 파일을 다시 내려받는 API는 없습니다.
5. 2단계: 업로드 예약
POST /api/v1/jobs
Content-Type: application/json
{
"schema_version": "upload-job/1.0",
"client_ref": "my-tool-2026-10-20-001",
"channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
"video": {"upload_id": "up_0123456789abcdef01234567",
"sha256": "e3b0…b855"},
"thumbnail": {"upload_id": "up_…", "sha256": "…"},
"metadata": {
"title": "영상 제목",
"description": "설명",
"tags": ["태그1", "태그2"],
"category_id": "22",
"default_language": "ko",
"self_declared_made_for_kids": false,
"contains_synthetic_media": false
},
"visibility": {"target": "scheduled", "publish_at": "2026-10-20T09:00:00Z"},
"notify_subscribers": true,
"not_before": "2026-10-20T08:00:00Z",
"upload_deadline": "2026-10-21T08:00:00Z",
"attestation": {
"actor_type": "human",
"approved_at": "2026-10-19T14:12:00Z",
"content_fingerprint": "e3b0…b855",
"source": "my-tool",
"approval_id": "review-1234"
}
}
칸 설명
schema_version(필수)"upload-job/1.0"고정.client_ref(필수)- 내 쪽에서 정하는 요청 이름(1~128자). 같은 값으로 같은 내용을 다시 보내면 새로 만들지 않고 기존 예약을
200으로 돌려줍니다. 네트워크가 끊겨 결과를 모를 때 안심하고 다시 보내세요. 같은 값에 다른 내용이면409 client_ref_conflict. channel_id(필수)- 올릴 YouTube 채널 ID(
UC…).GET /api/v1/channels의channel_id. video(필수)received상태인 영상 파일의upload_id와sha256(필수).size·content_type을 넣으면 일치하는지도 확인합니다. 같은 영상은 같은 채널에 살아 있는 예약이 있는 동안 다시 예약할 수 없습니다(409 video_already_scheduled). 다른 채널에는 예약할 수 있습니다.thumbnail(선택)- 썸네일 파일. 모양은
video와 같습니다. playlist_ids(선택)- 업로드가 끝난 뒤 영상을 넣을 재생목록 ID 목록(최대 5개, 형식
[A-Za-z0-9_-]{10,64}). 실패해도 업로드는 성공으로 두고 작업의post_steps에{"step","ok","code"}로 남깁니다. 채널 연결에youtube.force-ssl권한이 없으면scope_missing입니다(할당량 50). captions(선택)- 자막 파일 목록(최대 3개):
{"upload_id", "sha256", "language", "name"(150자 이하)}. 업로드 종류는caption(SRT·VTT, 2 MiB 이하,application/x-subrip·text/vtt·text/plain)이며 서버가 내용을 최소한으로 확인합니다. 업로드 성공 뒤 올리고 파일은 지웁니다(할당량 400, 결과는post_steps). metadata(필수)-
title필수, 100자 이하.description5000바이트(UTF-8) 이하.tags60개 이하, 합쳐서 500자 이하. 제목·설명·태그에<>는 쓸 수 없습니다. 한도를 넘으면 자르지 않고422 metadata_invalid로 거절하며reasons에 이유를 담습니다.category_id는 YouTube 카테고리 번호(문자열),default_language는 언어 코드(ko,en-US등).license("youtube"|"creativeCommon"),embeddable·public_stats_viewable·has_paid_product_placement(true/false),default_audio_language(언어 코드),recording_date(YYYY-MM-DD),localizations(언어 코드별{"title": 100자 이하, "description": 5000바이트 이하}, 최대 20개)는 모두 선택이며 빼면 지금 동작 그대로입니다. 서버가 지원하는 칸은GET /api/v1/capabilities로 알 수 있습니다.self_declared_made_for_kids(아동용 여부)와contains_synthetic_media(AI 등 합성·변형 콘텐츠 여부)는 반드시 true/false로 넣어야 합니다. visibility(선택)- 공개 범위 참고. 빼면
private.scheduled면publish_at필수이고, 지금과not_before보다 각각 15분 이상 뒤여야 합니다. notify_subscribers(선택)- 구독자 알림(기본 true).
not_before(선택)- 이 시각 이후에 YouTube로 올립니다. 빼면 바로.
upload_deadline(선택)- 이 시각까지 못 올리면
expired로 끝냅니다. 기본·최대 14일 뒤. social(선택)- 같은 영상을 SNS 계정에도 올립니다.
social:write권한이 필요하고 모양은 9-4를 보세요. attestation(필수)- 사람이 이 영상을 확인하고 올리기로 했다는 기록입니다.
actor_type은"human",content_fingerprint는 영상 sha256과 같아야 하고,approved_at(사람이 승인한 시각)은 24시간 이내여야 합니다.source·approval_id는 내 도구 쪽 기록용(선택, 128자 이하).
모르는 칸이 있으면 manifest_unknown_field로 거절합니다(오타 방지).
응답
새로 만들면 201, 같은 client_ref 재전송이면 200. 본문은 작업 하나입니다.
6. 3단계: 상태 확인
작업 조회
GET /api/v1/jobs/{job_id}
GET /api/v1/jobs?state=queued&limit=100
limit은 1~500(기본 100), 최근 만든 순입니다. 모르는 state는 400 state_invalid, 남의 작업은 404 not_found.
주요 칸: id, client_ref, state, visibility(실제로 보낼 값), requested_visibility, publish_at, not_before, upload_deadline, attempts, next_attempt_at, video_id, video_url, observed_status(YouTube가 알려 준 상태), error_code, created_at, finished_at, manifest.
| state | 뜻 |
|---|---|
awaiting_web_confirm | 웹에서 확인을 기다림(3장). 확인 전엔 올리지 않습니다. |
queued | 대기 중. not_before가 되면 올립니다. |
deferred | 잠시 미룸(하루 한도·일시 오류). next_attempt_at에 다시 시도합니다. |
uploading | YouTube로 보내는 중. |
uploaded | 완료. video_id·video_url이 채워집니다. |
failed | 실패(error_code 참고). 다시 하려면 파일을 새로 올리고 새 예약을 만드세요. |
unknown | 보냈지만 결과를 확인하지 못함. 중복 업로드를 막으려고 자동으로 다시 보내지 않습니다. 채널을 확인한 뒤 문의하세요. |
expired | upload_deadline까지 올리지 못함. |
canceled | 취소됨. |
이벤트(변경 알림)
GET /api/v1/events?after=0&limit=100
{"events": [{"seq": 41, "job_id": "job_…", "type": "video.uploaded",
"payload": {"video_id": "…", "privacy_status": "public"}, "created_at": "…"}],
"next_after": 41}
받은 마지막 next_after를 저장해 두고 다음에 after로 넘기면 새 이벤트만 옵니다(최대 500개). 1분에 한 번 정도 부르면 충분합니다. 주요 type: job.created, job.web_confirmed, job.rescheduled(웹에서 시각을 바꿈), job.uploading, job.deferred, video.uploaded, thumbnail.set, thumbnail.failed, job.failed, job.unknown, job.expired, job.canceled, video.edited·video.deleted(웹에서 영상을 고치거나 지움), connection.needs_reauth(채널을 다시 연결해야 함), connection.revoked. SNS 게시는 social.posted(올라감)·social.rescheduled·social.needs_reauth·social.revoked 같은 social.* 이벤트도 같은 목록에 섞여 옵니다. 모르는 type은 무시하세요.
자동 공개 이벤트: video.gate_blocked(신호 발견, payload.code), video.gate_published(자동 공개 완료), video.gate_stalled(처리 지연·공개 호출 반복 실패, 사람이 풀거나 취소해야 함). 공개되면 video.visibility_changed도 함께 옵니다.
7. 예약 취소
POST /api/v1/jobs/{job_id}/cancel
YouTube로 보내기 전(queued·deferred·awaiting_web_confirm)에만 됩니다. 그 밖에는 409 job_not_cancelable. 이미 올라간 영상은 YouTube 스튜디오에서 지우세요.
공개 방식(채널별)과 공개 승인. 채널마다 공개 방식이 있습니다. 기본 approval은 확인을 통과해도 사람이 승인해야 공개하고, 사람이 계정 화면에서 직접 켠 interval은 확인을 통과한 영상을 채널당 최소 n시간(1~168) 간격으로 승인 없이 공개합니다. 공개 방식을 API로 바꾸는 길은 없습니다(웹 계정 화면의 «편집»과 «모든 YouTube 채널에 같은 방식 적용»만). GET /api/v1/channels의 각 채널에 publish_policy: {"mode", "interval_hours"}가 조회용으로 붙습니다. {"action": "approve"}(공개 승인)는 jobs:publish 토큰으로 할 수 있습니다(checking·ready만, 그 밖은 409 publish_gate_not_approvable). 승인해도 신호 확인과 공개 직전 재확인은 건너뛰지 않습니다. 승인 뒤 신호가 나오면 공개하지 않고 blocked가 됩니다. 새 상태 ready(신호 없음이 쌓인 공개 후보)와 응답 칸 approved_at·awaiting_approval·next_publish_at(간격 방식 예상 시각)·publish_mode·interval_hours·egress_fallback이 추가됐고 기존 칸은 그대로입니다(capabilities.version 5). API로 취소(cancel)하면 어느 상태에서든 block_code에 CANCELED_VIA_API가 남아 위 visibility가 계속 409 visibility_gate_blocked입니다(취소가 승인 우회 통로가 되지 않게). 웹에서 사람이 취소하면 표시가 없습니다. 이벤트 video.gate_published에는 via(approved·interval·released)와 interval_hours가 붙고, 승인 대기가 90일 넘게 이어지면 비공개 그대로 canceled가 되며 video.gate_expired 이벤트가 나갑니다.
저작권 알림 메일과 «메일 확인 뒤 자동 공개». 수익 창출·추적형 Content ID 클레임은 YouTube API에 나오지 않고 채널 주인의 구글 계정 메일로만 옵니다. 사용자는 계정 화면에서 받은 수신 주소로 그 메일을 Gmail 필터로 전달하고, 출처(구글 계정)를 사람이 «필터까지 걸었음»으로 확인합니다(API로 바꾸는 길 없음). 세 번째 공개 방식 mail_checked는 그 연결이 메일 확인됨이고 영상의 claim 메일이 0건일 때만 승인 없이 공개하며, claim 메일이 온 영상은 어느 방식으로도 공개되지 않고 blocked(block_code CLAIM_MAIL, 이벤트 video.gate_blocked reason: claim_mail)가 됩니다. 이미 공개된 영상은 이벤트 video.claim_mail만 나갑니다. GET /api/v1/claims-mail?after=&limit=(jobs:read)은 내 claim 메일 기록(id, received_at, subject, video_ids, source_email)을 돌려주고, GET /api/v1/channels의 각 채널에는 읽기 전용 claims_mail_covered가, 게이트 칸에는 awaiting_reason이 추가됩니다(capabilities.version 7). 자세한 설계는 저장소 docs/specs/claims-mail.md.
고정 IP로 나갈 수 없을 때. 고정 IP가 배정된 채널은 그 IP로 확인·공개를 호출합니다. 막히면 10분 기다린 뒤에도 막혀 있을 때에만 서버 기본 출구로 진행합니다(게이트 라운드만의 예외이고 업로드는 계속 미룹니다). 기본 출구로 나간 사실은 publish_gate.egress_fallback과 감사 기록에 남습니다.
POST /api/v1/jobs/{job_id}/visibility (jobs:publish)
비공개로 올라간 영상(uploaded)을 사람 승인 증빙으로 한 번만 public 또는 unlisted로 바꿉니다. 본문: {"target": "public", "attestation": {"actor_type": "human", "approval_id": "…", "approved_at": "…", "content_fingerprint": "영상 sha256"}}. 증빙의 approval_id·approved_at·content_fingerprint가 예약을 만들 때의 승인과 같아야 하고(아니면 409), 승인은 24시간 안이어야 합니다. 지금 YouTube 값이 비공개일 때만 되고(409 visibility_not_private), 구글 앱 검증 전에는 409 visibility_forced_private입니다. 같은 요청을 다시 보내도 결과는 같습니다(200 {"id", "visibility"}). 지원 여부는 GET /api/v1/capabilities의 job_actions에 set_visibility가 있는지로 확인하고, GET /api/v1/jobs/{job_id} 응답의 video_status(privacy_status·upload_status·failure_reason·rejection_reason·region_restriction·claims, 못 읽으면 null)로 YouTube 판정을 봅니다.
POST /api/v1/jobs/{job_id}/publish-gate (jobs:publish)
저작권 신호 확인 게이트를 조작합니다. 본문 {"action": "cancel"}은 게이트를 끝내고 영상을 비공개로 둡니다(공개 호출 중에는 409 publish_gate_busy, 막힘·멈춤(blocked·stalled) 상태의 취소는 API로는 403 publish_gate_cancel_web_only이고 웹 화면에서 사람만 합니다). {"action": "reschedule", "publish_at": "2026-11-10T09:00:00Z"}는 checking 또는 ready 상태일 때만 공개 시각을 바꿉니다(사람이 승인한 영상을 앞당기는 요청은 409 publish_gate_approved_no_advance, 늦추기는 가능)(409 publish_gate_not_reschedulable). {"action": "release"}(막힘·멈춤을 풀고 공개)는 API로는 안 되고 403 publish_gate_release_web_only입니다. 막힘을 푸는 판단은 서비스 웹 화면에서 사람이 합니다. 게이트가 확인 중(waiting_upload·checking·ready·publishing)이거나 막힘·멈춤이거나, 막혔다가 취소돼 block_code가 남은 영상에 위 visibility 호출을 하면 409 visibility_gate_blocked입니다(확인 건너뛰기·막힘 우회 차단). 게이트가 없거나 끝난 영상은 전과 같습니다. 응답 {"id", "publish_gate"}. 지원 여부는 GET /api/v1/capabilities의 job_actions에 publish_gate가 있는지(version 4 이상)로 확인합니다.
GET /api/v1/jobs/{job_id}와 목록 응답에는 publish_gate(게이트가 없으면 null)가 추가됩니다: state(waiting_upload·checking·ready·publishing·published·published_external·blocked·stalled·canceled), final_target, publish_at, next_check_at, last_check_at, checks, clean_checks, block_code, signal(마지막으로 읽은 신호), note(위 한계 문장).
POST /api/v1/jobs/{job_id}/thumbnail (jobs:publish)
이미 올라간 영상(uploaded)의 썸네일을 사람 승인 증빙으로 바꿉니다. 본문: {"thumbnail": {"upload_id": "up_…", "sha256": "…"}, "attestation": {"actor_type": "human", "approval_id": "…", "approved_at": "…"}}. 이미지는 먼저 kind=thumbnail(JPEG·PNG, 2MB 이하, 640x360 이상, 가로세로비 16:9 근사)로 올려 받은 upload_id·sha256입니다. 증빙의 approval_id·approved_at은 예약을 만들 때의 승인과 같아야 하고(아니면 409), 승인은 업로드 완료 후 24시간 안이어야 합니다(attestation_stale). 같은 작업에는 같은 승인으로 서로 다른 이미지를 최대 3장(A/B/C)까지 바꿀 수 있고(넘으면 409 thumbnail_limit), 같은 승인을 다른 작업의 썸네일·공개 범위에 쓰면 409 attestation_approval_reused입니다(같은 작업의 공개 범위와 썸네일은 서로 막지 않습니다). 같은 이미지로 이미 바꾼 작업에 다시 보내면 YouTube를 부르지 않고 200 {"id", "thumbnail": {"sha256"}, "idempotent": true}입니다. 실패한 뒤 10분 동안은 429 thumbnail_retry_later. 할당량 50단위를 씁니다. 지원 여부는 GET /api/v1/capabilities의 job_actions에 set_thumbnail이 있는지로 확인합니다.
8. 채널·통계 읽기
GET /api/v1/channels (jobs:read)
연결한 채널 목록: id(연결 id, yc_…), channel_id(UC…), channel_title, label, state(active·needs_reauth·revoked) 등. 예약에는 channel_id, 아래 통계에는 연결 id를 씁니다.
GET /api/v1/channels/{연결 id}/overview (analytics:read)
GET /api/v1/channels/{연결 id}/videos?max_results=20&page_token=…
GET /api/v1/channels/{연결 id}/analytics?metrics=views,likes&dimensions=day&start=2026-09-01&end=2026-09-30
GET /api/v1/channels/{연결 id}/reports
videos:max_results1~50.videos항목의 선택 칸(못 얻으면null, 이유는 응답의perf_unavailable-filling은 서버가 캐시를 채우는 중이라 같은 목록을 다시 부르면 채워집니다. 한 번 부를 때 외부 호출은 최대 2회):views_48h(게시일 포함 3일 합 조회수 — Analytics가 일 단위라 정확한 48시간이 아닌 근사, 게시 3일 뒤부터),impressions·ctr(썸네일 노출 수·노출 클릭률 %, YouTube Reporting API의channel_reach_basic_a1; 분석 화면에서 보고서를 켠 채널만, 받은 일일 보고서 최대 7일 누적이며 기간은reach_window).analytics:metrics는views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained,subscribersLost,likes,comments,shares,viewerPercentage중에서.dimensions는day,video,insightTrafficSourceType,ageGroup,gender,country,deviceType중에서. 기간은 최대 365일, 빼면 최근 28일.analytics의start·end는YYYY-MM-DD(끝 날짜는 오늘까지),dimensions는 최대 2개,sort는 고른 지표·차원 이름(내림차순은 앞에-),max_results는 1~200입니다.video차원을 쓰면sort와max_results가 반드시 필요합니다(400 video_dimension_needs_sort).- 통계 API의 오류 code: 400
metric_not_allowed·dimension_not_allowed·sort_not_allowed·date_invalid·period_too_long·invalid_max_results·invalid_page_token·query_rejected, 403scope_missing(채널을 다시 연결해 권한 허용)·youtube_forbidden, 404channel_not_found·not_found_at_youtube, 409channel_mismatch·connection_not_active, 429quota_limit(하루 읽기 한도 또는 YouTube 쿼터 초과), 502youtube_error·youtube_unavailable·report_too_large·report_url_rejected, 503not_configured·egress_unavailable(채널에 정한 고정 IP로 나갈 수 없음 - 서버 기본 IP로는 부르지 않습니다). 형식은 같습니다.
8-1. 업로드 IP (한국 고정 IP)
관리자가 내게 배정한 한국 고정 IP가 있으면, 채널마다 그 IP로 올릴지 정할 수 있습니다(웹 계정 연결의 «업로드 IP»와 같습니다). 고정 IP를 받지 못했다면 ips가 비어 있고 모든 채널은 서버 기본 출구로 올라갑니다. 채널에 IP를 정하면 그 채널의 구글 접속(토큰 갱신·업로드·후속 단계)은 전부 그 IP로만 나가며, 터널이 끊겨 접속할 수 없으면 서버 기본 IP로 새지 않고 작업을 deferred(error_code EGRESS_UNAVAILABLE)로 10분마다 다시 확인하며 미룹니다.
GET /api/v1/egress (egress:read 또는 jobs:read)
PUT /api/v1/egress/channels/{connection_id} (egress:write)
curl -s "$BASE/egress" -H "Authorization: Bearer $TOOLULAH_TOKEN"
{"ips": [{"id": "eg_0123456789abcdef01234567", "label": "서울 1", "ip": "121.126.246.62",
"up": true, "checked_at": "2026-11-02T01:02:00Z", "enabled": true}],
"channels": [{"connection_id": "yc_…", "channel_id": "UC…", "title": "내 채널", "alias": "메인",
"egress_ip_id": "eg_0123456789abcdef01234567"}]}
curl -s -X PUT "$BASE/egress/channels/yc_…" -H "Authorization: Bearer $TOOLULAH_TOKEN" \
-H "Content-Type: application/json" -d '{"egress_ip_id": null}'
ips는 내게 배정된 IP만 나옵니다.up은 터널 상태(true연결됨·false끊김·null모름),checked_at은 그 상태를 확인한 시각입니다.channels는 살아 있는 내 YouTube 연결이며egress_ip_id가null이면 기본(서버) 출구입니다.title은 채널 이름,alias는 내가 붙인 별칭입니다.PUT본문은{"egress_ip_id": "eg_…"}또는{"egress_ip_id": null}(기본 출구로) 하나뿐이고, 응답은 바뀐channels항목 하나입니다. 다음 업로드부터 적용됩니다.- 오류:
403 egress_ip_not_assigned(내게 배정된 IP가 아님 - 없는 id도 같은 응답),409 egress_ip_disabled(관리자가 끈 IP),404 not_found(없거나 남의·해제된 연결). - 예전에 만든 토큰도
GET은jobs:read로 그대로 됩니다.PUT은egress:write가 있어야 하고jobs:write로는 안 됩니다(새 권한이 없는 예전 장치 토큰은 운영자가 부여합니다). 고정 IP의 배정·등록·삭제는 관리자 화면에서만 합니다.
10. 사진 게시 (카드뉴스)
글과 사진 여러 장을 Instagram 캐러셀·Threads·Facebook 페이지·TikTok 사진 게시로 한 번에 예약합니다. social:write 권한(만들기)과 social:read(조회)가 필요하고, 사진을 올리려면 uploads:write도 필요합니다.
10-1. 사진 올리기
4장와 같은 방식이고 kind가 image입니다. content_type은 image/jpeg만, 크기는 사진 한 장당 4 MiB까지이며, 한 번에 보내도 됩니다. 서버가 JPEG가 온전한지 확인하고 EXIF·GPS 등 위치/메타 정보를 지운 파일로 바꿉니다. 그래서 확인이 끝난 GET /uploads/{upload_id}의 sha256은 처음 선언한 값과 다를 수 있습니다(카드 요청에는 upload_id만 쓰므로 영향이 없습니다). 사진 한 장이 업로드 자리 하나이고 자리 열기는 시간당 30회입니다(한도).
curl -s -X POST "$BASE/uploads" -H "Authorization: Bearer $TOOLULAH_TOKEN" -H "Content-Type: application/json" \
-d '{"kind": "image", "content_type": "image/jpeg", "size": 183402, "sha256": "…"}'
10-2. 카드 만들기
POST /api/v1/cards (social:write)
curl -s -X POST "$BASE/cards" -H "Authorization: Bearer $TOOLULAH_TOKEN" -H "Content-Type: application/json" \
-d '{
"client_ref": "my-tool-card-001",
"body": "오늘의 카드뉴스 #정보",
"images": ["up_aaaaaaaaaaaaaaaaaaaaaaaa", "up_bbbbbbbbbbbbbbbbbbbbbbbb"],
"not_before": "2026-10-20T09:00:00Z",
"tiktok_title": "카드뉴스 제목",
"targets": [
{"connection_id": "sc_aaaaaaaaaaaaaaaaaaaaaaaa"},
{"connection_id": "sc_cccccccccccccccccccccccc", "tiktok": {"privacy_level": "SELF_ONLY", "allow_comment": true}}
]
}'
client_ref(필수)- 1~128자. 같은 값 + 같은 요청(본문·사진 순서·대상 계정·예약 시각·TikTok 옵션)이면 기존 카드를
200으로(요청 확인 전이라 TikTok을 다시 조회하지 않습니다), 하나라도 다르면409 client_ref_conflict. body- 본문. 한도: Instagram·Facebook 2,200자, Threads 500자, TikTok 4,000자(UTF-16 기준), 모든 플랫폼 공통 상한 10,000자.
images(필수, 빈 목록 가능)- 빈 목록
[]이면 글만 게시합니다. 이때 대상은 Threads·Facebook 페이지만 되고(Instagram·TikTok 은cards.error.TEXT_ONLY_PLATFORM), 본문이 있어야 합니다(사진도 본문도 없으면cards.error.NO_IMAGES). 사진upload_id를 보여 줄 순서대로. 내 것이고received인 JPEG 사진만 됩니다(아니면cards.error.IMAGE_UNAVAILABLE). 중복 불가. 한 카드의 최대 장수: Instagram 10, Facebook 10, Threads 20, TikTok 35(고른 플랫폼 중 가장 작은 값). not_before·targets- 9-3과 같습니다. 단 사진 게시물의 TikTok 옵션은
privacy_level·allow_comment·commercial만 있고,allow_duet·allow_stitch를 주면api.social.tiktok_photo_option으로 거절합니다. tiktok_title(선택)- TikTok을 고른 때만 쓰며 90자(UTF-16) 이하, 한 줄. 비우면 본문 첫 줄.
응답 201/200:
{"id": "cd_…", "body": "…", "tiktok_title": null, "image_count": 2,
"images": [{"position": 0, "upload_id": "up_…", "width": 1080, "height": 1350, "deleted": false}],
"not_before": "…", "deadline": "…", "created_at": "…", "canceled_at": null,
"posts": [{"id": "sp_…", "kind": "photo", "platform": "instagram", "card_id": "cd_…", "state": "queued", …}]}
사진 게시는 사진이 한 장 이상 있어야 합니다. 카드 한 장이 플랫폼마다 게시를 하나씩 만들며, 상태·성과·취소는 9장의 게시 API(/social/posts/{post_id})를 그대로 씁니다. 카드의 사진은 카드 보관 기간이 끝나면 지워집니다.
10-3. 카드 조회
GET /api/v1/cards/{card_id} (social:read)
curl -s "$BASE/cards/cd_0123456789abcdef01234567" -H "Authorization: Bearer $TOOLULAH_TOKEN"
10-2의 응답과 같은 모양입니다. 남의 카드는 404 not_found. 카드 사진 파일을 다시 내려받는 API는 없습니다(웹 상세 화면에서만).
11. 예약 일정
GET /api/v1/schedule?from=2026-10-20T00:00:00Z&to=2026-10-27T00:00:00Z (jobs:read)
curl -s "$BASE/schedule?from=2026-10-20T00:00:00Z&to=2026-10-27T00:00:00Z" -H "Authorization: Bearer $TOOLULAH_TOKEN"
{"entries": [{"type": "upload", "id": "job_…", "platform": "youtube", "connection_id": "yc_…",
"account": "내 채널", "title": "영상 제목", "state": "queued", "at": "2026-10-20T08:00:00.000000Z",
"publish_at": "2026-10-20T09:00:00.000000Z", "error_code": null, "video_url": null, "cancelable": true},
{"type": "card", "id": "sp_…", "platform": "threads", "connection_id": "sc_…", "account": "@me",
"title": "오늘의 카드뉴스", "state": "queued", "at": "…", "publish_at": null, "error_code": null,
"video_url": null, "cancelable": true}]}
- 웹 예약 일정 화면과 같은 통합 목록을 시간순(
at)으로 줍니다. 아직 끝나지 않은 것만 나옵니다: YouTube 업로드 대기·진행, YouTube 예약 공개, SNS 영상 게시, 사진 게시. type:upload(YouTube 업로드,id= 작업 id),publish(YouTube 예약 공개 시각 — 같은 작업이upload로도 나올 수 있음),sns(영상 게시),card(사진 게시). SNS 줄의id는 게시 id(sp_…)입니다.at은 그 일이 일어나는 시각입니다.from(포함)·to(미포함)는 시간대 있는 ISO-8601이고 둘 다 선택입니다. 한 번에 최대 90일까지 볼 수 있어, 둘 다 주면 90일을 넘길 수 없고(400 invalid_request)to를 빼면from(없으면 지금)부터 90일입니다.limit은 1~500(기본 200)이며 넘치면"truncated": true이니 기간을 좁혀 다시 부르세요. 응답의to는 실제로 적용된 끝 시각입니다. 틀린 값은400 invalid_request.cancelable이 true면 YouTube 줄은POST /jobs/{job_id}/cancel, SNS·카드 줄은POST /social/posts/{post_id}/cancel로 취소합니다. 시각 바꾸기는 웹에서만 됩니다.- SNS·카드 줄은 토큰에
social:read도 있을 때만 보입니다(jobs:read만 있으면 YouTube 줄만). - YouTube 작업과 SNS 게시를 각각 최대 2,000건까지 읽습니다. 남의 일정은 나오지 않습니다.
12. 도구 연결(기기 승인)
다른 사람이 쓸 업로드 도구를 만든다면, 사용자가 토큰을 복사해 붙이지 않고 코드 입력으로 연결하게 할 수 있습니다(RFC 8628 방식).
POST /api/v1/device/authorize (인증 없음)
{"client_name": "My Upload Tool"}
→ {"device_code": "…", "user_code": "ABCD-EFGH", "expires_in": 600, "interval": 5,
"verification_uri": "https://upload.toolulah.com/link",
"verification_uri_complete": "https://upload.toolulah.com/link?code=ABCD-EFGH"}
- 사용자에게
user_code와verification_uri를 보여 줍니다. 사용자가 로그인한 뒤 코드를 넣고 “승인”합니다. - 도구는
interval(5초)마다 토큰을 요청합니다.POST /api/v1/device/token {"device_code": "…"}기다리는 동안{"error": "authorization_pending"}, 너무 자주 부르면slow_down, 거절되면access_denied, 10분이 지나면expired_token입니다. - 승인되면 한 번만
{"access_token": "ust_…", "scopes": [...], "expires_at": "…", "username": "…"}를 줍니다. 90일짜리이고 권한은uploads:write jobs:read jobs:write analytics:read social:read social:write egress:read egress:write이고, 승인 화면 체크박스(기본 체크)가 켜져 있으면jobs:publish도 들어갑니다(끄면 빠지고, 나중에 웹 “API 토큰” 화면에서 켜고 끌 수 있습니다). - 연결을 끊을 때는
POST /api/v1/tokens/self/revoke로 그 토큰 스스로 회수하세요.
13. 한도
- API 요청: 사용자당 분당 120회(토큰을 여러 개 만들어도 합산).
- SNS 게시·카드 만들기(
POST /social/posts,POST /cards,social이 든POST /jobs)와 게시 취소(POST /social/posts/{post_id}/cancel): 사용자당 분당 30회(위 120회에도 포함). 카드 사진은 한 장이 업로드 자리 하나입니다. - 파일 자리 열기: 사용자당 시간당 30회. 동시에 받는 중인 파일 3개까지. 조각 PUT: 토큰당 분당 120회.
- 영상 20 GiB, 썸네일 50 MiB, 사진 4 MiB, 조각 64 MiB, 매니페스트·SNS 요청 본문 256 KB. SNS 대상은 한 요청에 30개까지.
- 한도를 넘으면
429와Retry-After(초) 헤더가 옵니다. 그만큼 기다렸다가 다시 보내세요.
14. 오류
오류 본문은 모두 같은 모양입니다. code는 프로그램이 읽는 영어 소문자 값이고, message는 사람이 읽는 문장(요청 언어)입니다. 이유가 여러 개일 수 있는 오류(metadata_invalid·social_invalid·card_invalid)에는 reasons 배열이 더해집니다.
{"code": "metadata_invalid", "message": "…", "reasons": ["TITLE_INVALID", "MADE_FOR_KIDS_UNSET"]}
{"code": "social_invalid", "message": "…", "reasons": ["social.error.caption_too_long_threads", "api.social.target_duplicate"]}
social_invalid·card_invalid의 reasons 항목은 웹 화면과 같은 문구 키(social.error.*, cards.error.*, web.error.schedule_*, schedule.error.target_*)이거나 API 모양 오류(api.social.*, api.cards.*)입니다. 한 번에 모두 알려 주므로 한꺼번에 고치세요.
api.social.invalid: 모르는 키가 있거나 객체가 아님 ·api.social.targets_invalid:targets가 없음·비어 있음·30개 초과 ·api.social.target_invalid: 대상 항목의 모양이 틀림 ·api.social.target_duplicate: 같은 계정을 두 번 고름social.error.target_unavailable: 모르는·남의·끊긴 계정 ·api.social.not_before_invalid: 시각이 시간대 있는 ISO-8601이 아님 ·api.social.caption_required·api.social.caption_invalid·api.social.share_to_feed_invalidapi.social.tiktok_invalid: TikTok 옵션의 모양이 틀림 ·api.social.tiktok_not_allowed: TikTok이 아닌 계정에tiktok을 줌 ·api.social.tiktok_photo_option: 사진 게시에 듀엣·스티치를 줌 ·api.cards.images_invalid·api.cards.body_invalid- 웹과 같은 규칙:
social.error.caption_too_long_{instagram|facebook|threads|tiktok},social.error.video_type,social.error.video_too_large_*,social.error.duration_*,social.error.tiktok_privacy_required·tiktok_commercial_choose·tiktok_branded_private·tiktok_cannot_post,cards.error.NO_IMAGES·IMAGE_UNAVAILABLE·IMAGE_DUPLICATE·IMAGES_TOO_MANY_*·BODY_TOO_LONG_*,web.error.schedule_past·schedule_too_far·schedule_invalid
| HTTP | 자주 보는 code |
|---|---|
| 400 | invalid_request(잘못된 쿼리·커서·JSON 포함), manifest_invalid, bad_content_range, length_mismatch, sha256_required, invalid_sha256, state_invalid |
| 401 | unauthorized |
| 403 | insufficient_scope, consent_required(웹에서 바뀐 약관 동의 필요), password_change_required, attestation_not_human |
| 404 | not_found(없거나 남의 것 — 작업·게시·카드·업로드 모두 같은 응답), video_upload_not_found, thumbnail_upload_not_found |
| 408 | timeout(조각 본문이 60초 동안 오지 않음 — 그 조각만 다시) |
| 409 | offset_mismatch, chunk_in_progress(같은 파일의 조각이 아직 처리 중), upload_closed, client_ref_conflict, video_not_received, video_not_ready, video_sha256_mismatch·video_size_mismatch·video_content_type_mismatch(썸네일도 thumbnail_*), video_already_scheduled, thumbnail_already_scheduled, attestation_fingerprint_mismatch, job_not_cancelable, post_not_cancelable |
| 413 / 415 | too_large, chunk_too_large / unsupported_type, magic_mismatch |
| 422 | 매니페스트 규칙 위반: metadata_invalid(+reasons), channel_not_connected, channel_id_invalid, client_ref_invalid, schema_version_unsupported, manifest_unknown_field, video_required, video_sha256_invalid(썸네일도 thumbnail_*), visibility_invalid, publish_at_invalid, publish_at_not_allowed, schedule_time_required, schedule_in_past_or_too_soon, schedule_before_upload, notify_subscribers_invalid, not_before_invalid, upload_deadline_invalid, upload_deadline_too_far, attestation_required, attestation_invalid, attestation_approved_at_required, attestation_stale(승인 24시간 지남)SNS: social_invalid(+reasons), card_invalid(+reasons) |
| 429 | rate_limited, too_many_active, too_many_failures |
| 500 / 507 | disk_error, server_error / user_storage_full, storage_full |
토큰을 여러 번 틀리면 그 IP가 잠시 막힙니다(429 too_many_failures).
15. 전체 예제(Python)
requests만 씁니다. 토큰은 환경변수 TOOLULAH_TOKEN에 넣으세요.
import hashlib
import os
import time
from datetime import datetime, timedelta, timezone
import requests
BASE = "https://upload.toolulah.com/api/v1"
H = {"Authorization": "Bearer " + os.environ["TOOLULAH_TOKEN"]}
VIDEO = "video.mp4"
def sha256_of(path):
h = hashlib.sha256()
with open(path, "rb") as f:
for block in iter(lambda: f.read(1024 * 1024), b""):
h.update(block)
return h.hexdigest()
def upload(path, kind, content_type):
size, digest = os.path.getsize(path), sha256_of(path)
r = requests.post(f"{BASE}/uploads", headers=H, timeout=30,
json={"kind": kind, "content_type": content_type, "size": size, "sha256": digest})
r.raise_for_status()
up = r.json()
offset, chunk = up["offset"], up["chunk_size"]
with open(path, "rb") as f:
while offset < size:
f.seek(offset)
data = f.read(chunk)
rng = f"bytes {offset}-{offset + len(data) - 1}/{size}"
r = requests.put(f"{BASE}/uploads/{up['upload_id']}", data=data, timeout=300,
headers={**H, "Content-Range": rng, "Content-Type": "application/octet-stream"})
if r.status_code == 409 and r.json().get("code") == "offset_mismatch":
offset = r.json()["offset"] # 서버가 가진 위치부터 다시
continue
r.raise_for_status()
offset = r.json()["offset"]
while True: # 서버 확인(sha256·형식) 기다리기
state = requests.get(f"{BASE}/uploads/{up['upload_id']}", headers=H, timeout=30).json()
if state["state"] == "received":
return up["upload_id"], digest
if state["state"] == "failed":
raise RuntimeError(state["error_code"])
time.sleep(5)
def iso(dt):
return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
channel = requests.get(f"{BASE}/channels", headers=H, timeout=30).json()["channels"][0]["channel_id"]
upload_id, digest = upload(VIDEO, "video", "video/mp4")
now = datetime.now(timezone.utc)
manifest = {
"schema_version": "upload-job/1.0",
"client_ref": "demo-" + digest[:16],
"channel_id": channel,
"video": {"upload_id": upload_id, "sha256": digest},
"metadata": {"title": "API로 올린 영상", "description": "", "tags": [],
"self_declared_made_for_kids": False, "contains_synthetic_media": False},
"visibility": {"target": "unlisted"},
"attestation": {"actor_type": "human", "approved_at": iso(now), "content_fingerprint": digest,
"source": "demo-script"},
}
r = requests.post(f"{BASE}/jobs", headers=H, json=manifest, timeout=30)
r.raise_for_status()
job = r.json()
print(job["id"], job["state"]) # jobs:publish 가 있으면 queued, 없으면 awaiting_web_confirm
while job["state"] not in ("uploaded", "failed", "unknown", "expired", "canceled"):
time.sleep(30)
job = requests.get(f"{BASE}/jobs/{job['id']}", headers=H, timeout=30).json()
print(job["state"], job.get("video_url"))
질문이나 문제가 있으면 support@toolulah.com로 알려 주세요. 사용법 전반은 도움말에 있습니다.
9. SNS 게시 (Instagram · Facebook · Threads · TikTok)
받은 영상을 YouTube 대신(또는 YouTube와 함께) SNS 계정에 게시·예약합니다. SNS 계정은 웹 계정 연결에서 먼저 연결해야 하고, API로는 연결·해제할 수 없습니다. 이 장의 API는
social:read·social:write권한이 필요합니다(2장). 예시의$BASE는https://upload.toolulah.com/api/v1,$TOOLULAH_TOKEN은 내 토큰입니다.9-1. 연결된 SNS 계정
curl -s "$BASE/social/connections" -H "Authorization: Bearer $TOOLULAH_TOKEN" {"connections": [{"id": "sc_0123456789abcdef01234567", "platform": "instagram", "account_name": "@my_account", "label": "메인", "display_name": "@my_account · 메인", "state": "active", "last_error_code": null, "authorized_at": "…", "capabilities": {"post": true, "insights": true, "messages": false}}]}platform:instagram·facebook·threads·tiktok.state:active(게시 가능)·needs_reauth(웹에서 다시 연결해야 함). 연결을 해제한 계정은 나오지 않습니다.capabilities:post게시 가능,insights성과 지표를 읽을 권한이 있음,messages메시지(받은편지함) 권한이 있음.id(sc_…)를 씁니다.9-2. 채널 그룹
curl -s "$BASE/groups" -H "Authorization: Bearer $TOOLULAH_TOKEN" {"groups": [{"id": "tg_…", "name": "쇼츠 전체", "created_at": "…", "updated_at": "…", "members": [{"kind": "youtube", "connection_id": "yc_…", "platform": "youtube", "name": "내 채널", "alive": true}, {"kind": "social", "connection_id": "sc_…", "platform": "threads", "name": "@me", "alive": true}]}]}그룹은 이름 붙은 선택 묶음일 뿐이라 서버가 그룹을 "실행"하지 않습니다. 구성원
connection_id를 골라channel_id(8장)나 SNStargets로 쓰세요. 토큰에jobs:read만 있으면 YouTube 구성원만,social:read만 있으면 SNS 구성원만 보입니다. 그룹 만들기·고치기·지우기는 웹에서만 됩니다.9-3. 영상 SNS 게시·예약
curl -s -X POST "$BASE/social/posts" \ -H "Authorization: Bearer $TOOLULAH_TOKEN" -H "Content-Type: application/json" \ -d '{ "client_ref": "my-tool-2026-10-20-sns-001", "video": {"upload_id": "up_0123456789abcdef01234567", "sha256": "e3b0…b855"}, "caption": "새 영상 올렸어요 #쇼츠", "share_to_feed": true, "not_before": "2026-10-20T09:00:00Z", "targets": [ {"connection_id": "sc_aaaaaaaaaaaaaaaaaaaaaaaa"}, {"connection_id": "sc_bbbbbbbbbbbbbbbbbbbbbbbb", "not_before": "2026-10-20T12:00:00Z"}, {"connection_id": "sc_cccccccccccccccccccccccc", "tiktok": {"privacy_level": "SELF_ONLY", "allow_comment": true, "allow_duet": false, "allow_stitch": false, "commercial": {"brand_organic": false, "brand_content": false}}} ] }'client_ref(필수)video(필수)received상태 영상의upload_id와sha256(둘 다 필수). MP4·MOV만 됩니다(WebM 불가). 남의 파일이거나 없으면404 video_upload_not_found, 아직 다 안 받았으면409 video_not_received.caption(필수)share_to_feed(선택, 기본 true)not_before(선택)targets(필수, 1~30개)connection_id(필수, 중복 불가) ·not_before(선택, 이 계정만 다른 시각) ·tiktok(TikTok 계정에만). 내 것이 아니거나 끊긴 계정은 존재 여부를 알려 주지 않고 모두social.error.target_unavailable입니다.TikTok 옵션 (웹과 같은 규칙)
privacy_level은 필수이고 기본값이 없습니다. 값은PUBLIC_TO_EVERYONE·MUTUAL_FOLLOW_FRIENDS·FOLLOWER_OF_CREATOR·SELF_ONLY중 그 TikTok 계정이 지금 허용하는 것만 됩니다(서버가 TikTok에 물어보며, 요청에서 고른 TikTok 계정에만 묻고 결과는 최대 90초 동안 서버 메모리에 재사용합니다 — 그 사이 TikTok에서 허용 범위가 바뀌면 그 요청은 이전 값으로 검사될 수 있습니다).allow_comment·allow_duet·allow_stitch: 기본 꺼짐. 크리에이터가 끈 항목은 켜도 꺼진 채로 저장됩니다.commercial: 상업 콘텐츠 공개. 객체로 주면(true도 가능) 켠 것이고, 그러면brand_organic(내 브랜드)·brand_content(제휴 콘텐츠) 중 하나 이상이 true여야 합니다. 제휴 콘텐츠는SELF_ONLY로 올릴 수 없습니다.응답
201(새로 만듦) 또는200(같은 요청의 재전송):{"batch_id": "bt_…", "created": true, "posts": [{"id": "sp_…", "kind": "video", "platform": "threads", "connection_id": "sc_…", "account_name": "@me", "state": "queued", "job_id": null, "card_id": null, "batch_id": "bt_…", "caption": "…", "not_before": "…", "deadline": "…", "attempts": 0, "next_attempt_at": null, "error_code": null, "permalink": null, "created_at": "…", "finished_at": null, "remote_deleted": false, "performance": null}]}멱등: 같은
client_ref로 같은 요청(영상·본문·share_to_feed·not_before·대상 계정별 예약 시각·TikTok 옵션까지 같은 것)을 다시 보내면 새로 만들지 않고 기존 게시를200으로 돌려줍니다. 표기만 다른 같은 요청(JSON 키 순서, 생략한 기본값, 시간대 표기)은 같은 요청입니다. 같은client_ref에 내용이 하나라도 다르면409 client_ref_conflict. 취소된 게시도 «이미 있음»으로 셉니다. 전부 취소한 뒤 같은 요청을 다시 보내도 새로 올리지 않고 기존(취소된) 게시를200으로 돌려줍니다. 다시 올리려면 새client_ref를 쓰세요. 같은 영상을 같은 계정에 아직 살아 있는 게시가 있는 채로 다른client_ref로 보내면409 video_already_scheduled입니다.검증에 실패하면
422 social_invalid이고reasons에 이유가 모두 들어 있습니다(오류). 아무것도 만들어지지 않습니다.9-4. 영상 작업과 같이 올리기 (
POST /jobs의social)YouTube 업로드 예약(5장)의 매니페스트에 선택 필드
social을 더하면 같은 영상으로 SNS 게시도 같은 묶음에 만들어집니다(웹의 "같이 올릴 SNS"와 같습니다). 토큰에는jobs:write와social:write가 모두 있어야 하고, 없으면403 insufficient_scope입니다.social이 없거나null이면 기존과 똑같이 동작합니다.curl -s -X POST "$BASE/jobs" -H "Authorization: Bearer $TOOLULAH_TOKEN" -H "Content-Type: application/json" \ -d '{ "schema_version": "upload-job/1.0", "client_ref": "…", "channel_id": "UC…", "video": {…}, "metadata": {…}, "attestation": {…}, "social": {"caption": "(선택)", "share_to_feed": true, "targets": [{"connection_id": "sc_…"}, {"connection_id": "sc_…", "not_before": "2026-10-20T12:00:00Z"}]}}'social의 칸은 9-3의caption·share_to_feed·targets와 같습니다.caption을 비우면제목 + 빈 줄 + 설명이 본문이 됩니다.not_before를 주면 그 계정만 따로입니다.422 social_invalid와 함께 작업도 만들어지지 않습니다."social_posts"배열(9-3의 게시 모양)이 더해집니다. 같은client_ref재전송(200)이면 이미 만들어진 게시를 돌려주고 이번 요청의social은 보지 않았다는 뜻으로"social_ignored": true가 붙습니다(내용이 달라도 409가 아니라 무시됩니다 — 바꾸려면 새client_ref로 보내세요). 처음 만들 때는 이 칸이 없습니다.9-5. 게시 상태·성과 조회
GET /api/v1/social/posts?state=&job_id=&limit=50&after=sp_… (social:read) GET /api/v1/social/posts/{post_id} (social:read)curl -s "$BASE/social/posts?state=posted&limit=20" -H "Authorization: Bearer $TOOLULAH_TOKEN" {"posts": [{"id": "sp_…", "state": "posted", "permalink": "https://www.threads.net/…", "error_code": null, "performance": {"state": "ok", "metrics": {"views": 120, "likes": 8}, "fetched_at": "…"}, …}], "next_after": null}limit1~200(기본 50). 다음 쪽은 응답의next_after를after로 넘기세요(null이면 끝).state와job_id(9-4로 만든 묶음)로 거를 수 있습니다. 모르는state는400 state_invalid, 잘못된after는400 invalid_request.404 not_found입니다.permalink는https주소일 때만 나옵니다.error_code는failed·deferred·unknown일 때 이유 코드입니다.performance는posted인 게시에만 있습니다.state:ok(metrics에 조회·좋아요 등 숫자),pending(아직 읽지 않음),need_scope(그 계정이 성과 읽기 권한을 아직 허용하지 않음 — 웹에서 다시 연결),error. 지표 이름은 플랫폼마다 다릅니다.queuednot_before가 되면 보냅니다. 이 상태에서만 취소할 수 있습니다.deferrednext_attempt_at에 다시 시도합니다. 취소 가능.sending·processingpostedpermalink가 채워질 수 있습니다.failederror_code참고). 자동으로 다시 보내지 않습니다. 새로 만드세요.unknownexpireddeadline까지 보내지 못함.canceled9-6. 게시 취소
POST /api/v1/social/posts/{post_id}/cancel (social:write)아직 보내기 전(
queued·deferred)만 취소되고 갱신된 게시를 돌려줍니다. 그 밖의 상태는409 post_not_cancelable, 남의 게시는404.9-7. 웹에서만 하는 일
다음은 재인증이나 사람의 확인이 필요한 동작이라 API로 열지 않았습니다: SNS 계정 연결·해제·별칭, 이미 올라간 글의 수정·삭제, 예약 시각 바꾸기, 채널 그룹 만들기·고치기·지우기, 댓글 자동 응답 규칙, 받은편지함.