開発者 API
1. 概要
自分のプログラムから、動画を YouTube チャンネルにアップロード予約し(1~8章)、同じ動画や写真を SNS アカウント(Instagram・Facebook・Threads・TikTok)にも投稿・予約する(9~11章)ための API です。YouTube へのアップロードは次の 3 ステップです。
- ファイルをアップロード: 動画(必要ならサムネイルも)をこのサービスに送ります。大きなファイルは小さな塊(チャンク)に分けて送り、途切れたら続きから送れます。
- 予約を作成: アップロードしたファイルの 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 個までです。
- トークンは、作成したアカウントとそのアカウントが接続したチャンネルにのみ使えます。
- トークンをコードやリポジトリに入れず、環境変数などのシークレット保管先に置いてください。
権限(スコープ)
| 権限 | できること |
|---|---|
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" が使えるのは Web フォームだけで、API リクエストの "off" は jobs:publish 権限があっても "auto" として扱われ、レスポンスの warnings に PUBLISH_GATE_OFF_IGNORED が付きます。private はゲートなしで非公開のままです。公開が許可される前(上記の強制非公開)に作ったジョブにもゲートが作られます: アップロードは今までどおり強制非公開で、公開は公開許可がオンになり確認を通ったあとだけです(オフの間は待つだけで停止しません)。入力の検証、Web での確認(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 著作権シグナルなし」です。Studio の内部 API や Cookie は使いません。 - クライアントの注意: ゲートのあるジョブは
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 以下のファイルは 1 回で送っても構いません。 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": "ja",
"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 文字以下。descriptionは 5000 バイト(UTF-8)以下。tagsは 60 個以下で、合計 500 文字以下。 タイトル・説明・タグに<>は使えません。上限を超えると切り詰めずに422 metadata_invalidで拒否し、reasonsに理由を入れます。category_idは YouTube のカテゴリ番号(文字列)、default_languageは言語コード(ja、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 です。本文はジョブ 1 件です。
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 | しばらく延期(1 日の上限・一時的なエラー)。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 分に 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 Studio で削除してください。
チャンネルごとの公開方法と公開の承認。 チャンネルごとに公開方法があります。既定の approval は、確認を通過しても人が承認して初めて公開します。人がアカウント画面で自分で有効にした interval は、確認を通過した動画をそのチャンネルで最低 n 時間(1~168)あけて承認なしで公開します。公開方法をAPI で変更する手段はありません(Web のアカウント画面の「編集」と「すべての 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 になります(取り消しが承認の回避手段にならないように)。人が Web 画面で取り消した場合は印が付きません。イベント video.gate_published には via(approved・interval・released)と interval_hours が付き、承認待ちが 90 日を超えると動画は非公開のまま canceled になり、video.gate_expired イベントが出ます。
著作権通知メールと「メール確認後に自動公開」。 収益化型・追跡型の Content ID クレームは YouTube API には出ず、チャンネル所有者の Google アカウントのメールでのみ届きます。ユーザーはアカウント画面の受信アドレスへ Gmail フィルタでそのメールを転送し、出典(Google アカウント)を人が「フィルタを設定済み」で確認します(API で変更する手段はありません)。3 つ目の公開方法 mail_checked は、その接続がメール確認済みで動画のクレームメールが 0 件のときだけ承認なしで公開します。クレームメールが届いた動画はどの方法でも公開されず blocked(block_code CLAIM_MAIL、イベント video.gate_blocked の reason: claim_mail)になり、すでに公開済みの動画にはイベント video.claim_mail だけが出ます。GET /api/v1/claims-mail?after=&limit=(jobs:read)は自分のクレームメール記録(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)、Google のアプリ審査前は 409 visibility_forced_private です。同じリクエストを再送しても結果は同じです(200 {"id", "visibility"})。対応の有無は GET /api/v1/capabilities の job_actions に set_visibility があるかで確認し、YouTube の判定は GET /api/v1/jobs/{job_id} の video_status(privacy_status・upload_status・failure_reason・rejection_reason・region_restriction・claims、読めない場合は null)で確認します。
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 で、Web 画面で人が行います)。{"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 です。解除の判断はサービスの Web 画面で人が行います。ゲートが確認中(waiting_upload・checking・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・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_resultsは 1~50。videos各項目の任意フィールド(取得できないときはnull、理由はレスポンスのperf_unavailable。fillingはサーバーがキャッシュを埋めている最中で、同じ一覧を再度呼ぶと埋まります。1 回の呼び出しで外部呼び出しは最大 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(1 日の読み取り上限または YouTube のクォータ超過)、502youtube_error・youtube_unavailable・report_too_large・report_url_rejected、503not_configured・egress_unavailable(チャンネルの固定IPで接続できない - サーバーの標準IPでは接続しません)。形式は同じです。
8-1. 投稿IP(韓国の固定IP)
管理者から韓国の固定IPを割り当てられている場合、チャンネルごとにそのIPで投稿するかを決められます(ウェブのアカウント連携の「投稿IP」と同じです)。割り当てがなければ ips は空で、すべてのチャンネルはサーバーの標準出口で投稿されます。チャンネルにIPを設定すると、そのチャンネルのGoogleへの接続(トークン更新・アップロード・後続ステップ)はすべてその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}(標準出口に戻す)の1つだけで、レスポンスは更新されたchannelsの項目1件です。次の投稿から適用されます。- エラー:
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 のみ、サイズは写真 1 枚あたり 4 MiB までで、1 回で送って構いません。サーバーが JPEG が正しいことを確認し、EXIF・GPS などの位置情報やメタ情報を消したファイルに置き換えます。そのため、確認後の GET /uploads/{upload_id} の sha256 は、最初に宣言した値と異なることがあります(カードのリクエストでは upload_id だけを使うので影響はありません)。写真 1 枚が 1 つのアップロード枠を使い、枠を開けるのは 1 時間あたり 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 には再問い合わせしません)、1 つでも違えば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)。重複不可。1 枚のカードの最大枚数: 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)以下で 1 行。空なら本文の 1 行目。
レスポンス 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", …}]}
写真投稿には写真が 1 枚以上必要です。1 枚のカードはプラットフォームごとに投稿を 1 つずつ作り、状態・成果・取り消しは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 リクエスト: ユーザーあたり 1 分 120 回(トークンを複数作っても合算)。
- SNS 投稿・カードの作成(
POST /social/posts、POST /cards、socialを含むPOST /jobs)と投稿の取り消し(POST /social/posts/{post_id}/cancel): ユーザーあたり 1 分 30 回(上の 120 回にも含まれます)。カードの写真 1 枚が 1 つのアップロード枠を使います。 - ファイル枠の作成: ユーザーあたり 1 時間 30 回。同時に受信中のファイルは 3 つまで。チャンクの PUT: トークンあたり 1 分 120 回。
- 動画 20 GiB、サムネイル 50 MiB、写真 4 MiB、チャンク 64 MiB、マニフェスト・SNS リクエスト本文 256 KB。SNS の対象は 1 リクエストにつき 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: 同じアカウントを 2 回選んだ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章)や SNS のtargetsに使ってください。トークンに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で 1 つでも内容が違うと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}limitは 1~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になると送信します。この状態(とdeferred)でのみ取り消せます。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 アカウントの接続・解除・別名、すでに投稿された記事の編集・削除、予約時刻の変更、チャンネルグループの作成・編集・削除、コメント自動返信ルール、受信トレイ。