ランダム投稿追加API 仕様書

用途	利用者が管理するランダム投稿グループに、外部から投稿を1件追加する
認証方式	Bearer トークン（APIトークン・ユーザー単位）
通信	HTTPS 推奨
データ形式	JSON（Request / Response ともに Content-Type: application/json）

• 追加した投稿は、既存のランダム投稿プログラムの対象となり、設定に応じて自動投稿の候補になります。
• トークンはユーザー単位で発行され、そのユーザーが所有する任意のランダム投稿グループに対して投稿を追加できます。
• 投稿本文（post）と画像URL（media / media_2 / media_3 / media_4）のどちらかがあれば追加可能です。画像のみの投稿（本文なし）も利用できます。

すべてのリクエストで、HTTP ヘッダーに API トークンを付与してください。

ヘッダー名	値
Authorization	Bearer {APIトークン}
Content-Type	application/json
Accept	application/json（推奨。エラー時にJSONで返却されます）

例

Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/json

• トークンが未設定・無効・期限切れの場合は 401 Unauthorized が返却されます。
• グループIDがトークンに紐づくユーザーのものでない場合は 404 Not Found が返却されます（他ユーザーのグループの有無は応答から判別できません）。

APIトークンは、XNINJAの管理画面から発行します。

1. 管理画面にログインする。
2. プロフィール画面の APIトークン管理 を開く（https://xninja.net/admin/api-tokens）。
3. 「新しいトークンを発行」でトークン名（例: 自社ツール用）を入力し、発行する。
4. 表示されたトークン文字列を必ず控える。
   ※ トークンは発行時に一度だけ表示され、再表示はできません。

トークンの削除・再発行も同じ画面から行えます。トークンを削除すると、そのトークンによるAPIアクセスは直ちにできなくなります。

メソッド	URL	説明
POST	/api/randompost-groups/{group_id}/posts	指定したランダム投稿グループに投稿を1件追加する

ベースURL: https://xninja.net

フルURL例: https://xninja.net/api/randompost-groups/123/posts

パスパラメータ

名前	型	必須	説明
group_id	整数	○	ランダム投稿グループのID。管理画面の「ランダム投稿グループ」一覧で確認できます。

5.1 リクエストボディ（JSON）

項目	型	必須	説明
post	文字列 | null	△	投稿本文。最大 280 文字（X の標準投稿上限）。post と media 系のどちらかは必須（画像のみの投稿可）。
media	文字列 | null	△	画像URL（1枚目）。最大 2,048 文字。
media_2	文字列 | null	-	画像URL（2枚目）。最大 2,048 文字。
media_3	文字列 | null	-	画像URL（3枚目）。最大 2,048 文字。
media_4	文字列 | null	-	画像URL（4枚目）。最大 2,048 文字。
stop_delete_flg	整数	-	0 = 通常（自動削除の対象）、1 = 削除しない。未指定時は 0。
public_flg	整数	-	1 = 公開（ランダム投稿の候補）、0 = 非公開。未指定時は 1。
priority	整数	-	実行順序。数値が小さいほど先。0〜9999。未指定時は 0。プログラムの「指定した順序で投稿する」がオンのときのみ使われます。
reference_tag	文字列 | null	-	参照タグ。他投稿本文の %%{タグ名}%% をこのタグの最新投稿済みURLに置換。最大 64 文字。

5.2 リクエスト例

テキストのみ（画像なし）

{
  "post": "本日の一言です。",
  "media": null,
  "stop_delete_flg": 0
}

画像URLのみ（本文なし）

{
  "post": null,
  "media": "https://example.com/images/photo.jpg",
  "stop_delete_flg": 0
}

画像URLを複数指定（最大4枚）

{
  "post": "最大4枚まで画像を付けられます。",
  "media": "https://example.com/images/1.jpg",
  "media_2": "https://example.com/images/2.jpg",
  "media_3": "https://example.com/images/3.jpg",
  "media_4": "https://example.com/images/4.jpg",
  "stop_delete_flg": 0
}

公開フラグ・実行順序を指定する場合

{
  "post": "先に出したい投稿です。",
  "public_flg": 1,
  "priority": 1,
  "stop_delete_flg": 0
}

不正例: post も media 系もない場合は 422 エラーになります。

6.1 成功時（201 Created）

キー	型	説明
data	オブジェクト	作成された投稿の情報
data.id	整数	投稿のID
data.randompost_group_id	整数	ランダム投稿グループID
data.post	文字列	投稿本文
data.media〜data.media_4	文字列 | null	画像URL（1〜4枚目）
data.stop_delete_flg	整数	削除除外フラグ（0 または 1）
data.public_flg	整数	公開フラグ（0 または 1）
data.priority	整数	実行順序（小さい数字ほど先）
data.reference_tag	文字列 | null	参照タグ
data.created_at	文字列	作成日時（ISO 8601形式）

例

{
  "data": {
    "id": 12345,
    "randompost_group_id": 1,
    "post": "今日の一枚です。",
    "media": "https://example.com/images/photo.jpg",
    "media_2": null,
    "media_3": null,
    "media_4": null,
    "stop_delete_flg": 0,
    "public_flg": 1,
    "priority": 0,
    "reference_tag": null,
    "created_at": "2026-03-08T12:00:00.000000Z"
  }
}

7.1 401 Unauthorized

トークンが無効・未設定・期限切れの場合。

{
  "message": "Unauthenticated."
}

7.2 404 Not Found

指定した group_id のグループが存在しない、または認証ユーザーが所有していない場合。

{
  "message": "ランダム投稿グループが見つかりません。"
}

7.3 422 Unprocessable Entity

バリデーションエラーまたはプラン上限超過。

{
  "message": "The given data was invalid.",
  "errors": {
    "post": ["投稿本文と画像URLのどちらかは必須です。"]
  }
}

{
  "message": "このグループにはこれ以上追加できません。",
  "errors": {
    "randompost_group_id": ["プラン上限（10件）に達しています。"]
  }
}

7.4 429 Too Many Requests

レート制限を超えた場合。

{
  "message": "Too Many Attempts."
}

8.1 プラン別の投稿数上限

プラン	1グループあたりの投稿数上限（目安）
Free	10件
Basic / Pro / VIP / Unlimited	9,999件

上限に達しているグループへ追加しようとした場合は 422 でエラーが返ります。詳細はプランをご確認ください。

8.2 レート制限

同一トークン（同一ユーザー）あたり、1分間に 60 リクエストまでです。これを超えると 429 Too Many Requests が返却されます。

8.3 その他

• 対象となるのは、有効（無効化されていない）なランダム投稿グループのみです。
• 投稿本文（post）は 280 文字以内、画像URL（media 系）は 2,048 文字以内、参照タグ（reference_tag）は 64 文字以内で指定してください。
• X への実際の投稿 — X には送信文字数の上限があります（標準アカウントでは目安 280 文字）。API で登録できても、上限を超える本文は X へ送信されません。ランダム投稿プログラム実行ログで投稿に失敗している場合は、本文を短くする、%%{タグ名}%% を展開したあとの文字数も含めて文字数を調整してください。

cURL

curl -X POST "https://xninja.net/api/randompost-groups/1/posts" \
  -H "Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"post":"APIから追加した投稿です。","media":null,"stop_delete_flg":0}'

JavaScript (fetch)

const response = await fetch('https://xninja.net/api/randompost-groups/1/posts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    post: 'APIから追加した投稿です。',
    media: null,
    stop_delete_flg: 0,
  }),
});

const data = await response.json();
if (response.ok) {
  console.log('作成された投稿ID:', data.data.id);
} else {
  console.error('エラー:', data.message, data.errors);
}

Python (requests)

import requests

url = "https://xninja.net/api/randompost-groups/1/posts"
headers = {
    "Authorization": "Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
    "Accept": "application/json",
}
payload = {
    "post": "APIから追加した投稿です。",
    "media": None,
    "stop_delete_flg": 0,
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if response.status_code == 201:
    print("作成された投稿ID:", data["data"]["id"])
else:
    print("エラー:", data.get("message"), data.get("errors"))