# AICU X (Twitter) Gateway Skill

> 自分の X API キーを持たずに、X のポスト・プロフィール・タイムライン・検索を読む。所有証明（このアカウントは私のものです）もここで。

## Package Info

- **Name**: aicu-x
- **Version**: 0.1.0 (Beta)
- **Base URL**: https://api.aicu.ai/v1/x
- **Auth**: APIキー必須 (Bearer Token)・スコープ `x`
- **⚠️ 1 本のポストを確認するだけなら `status/:id`（100 AP）。`timeline`（2,250 AP）は 22 倍**です。
  id が分かっているなら `status` で足ります。反応の数もそちらで返ります。
  `timeline` が要るのは「id が分からない」「最近の複数本をまとめて見たい」ときだけです。
- **課金**: 成功（HTTP 200）時のみ。`status` / `user` は 0 AP（**2026-09-23 05:00 UTC から上流参照 1 回 100 AP・キャッシュヒットは 0**）、`timeline` / `search` は 2,250 AP/回。サーバ側キャッシュあり（status 10 分・user 12〜24 時間・search 5 分）

## Quick Start

```bash
# 1) ポストを 1 件読む（x.com/<user>/status/<id> の末尾の数字が id）
curl https://api.aicu.ai/v1/x/status/1834567890123456789 \
  -H "Authorization: Bearer aicu_live_xxx"
# → {"id":"1834567890123456789","text":"...","author":{"username":"AICUai","name":"AICU","profile_image_url":"https://..."}}

# 2) プロフィール
curl https://api.aicu.ai/v1/x/user/AICUai -H "Authorization: Bearer aicu_live_xxx"

# 3) 最近のポスト（2,250 AP）
curl "https://api.aicu.ai/v1/x/timeline/AICUai?limit=10" -H "Authorization: Bearer aicu_live_xxx"

# 4) 検索（2,250 AP）
curl "https://api.aicu.ai/v1/x/search?q=AICU&limit=10" -H "Authorization: Bearer aicu_live_xxx"
```

## Endpoints

### 断られたときの読み分け（2026-09-28〜）

| code | status | すること |
|---|---|---|
| `insufficient_credits` | 402 | AP を足す |
| `key_daily_cap_exceeded` | 429 | **待つ。AP を足しても直らない**（鍵ごとの日次上限） |
| `daily_cap_exceeded` | 429 | 待つ |
| `service_budget_exhausted` | 503 | こちらの都合。待つ |

| Method | Path | 何が返るか | AP |
|---|---|---|---|
| GET | `/v1/x/status/:id` | ポスト本文と著者（`id` / `text` / `author.username` / `author.name` / `author.profile_image_url`）＋ `created_at`（ISO）＋ 添付 `media[]`（`type` photo/video/animated_gif・`url`・`preview_image_url`・`width`・`height`・`alt_text`。無ければ `[]`） | 0 |
| GET | `/v1/x/user/:username` | プロフィール | 0 |
| GET | `/v1/x/timeline/:username?limit=10` | 最近のポスト一覧 | 2,250 |
| GET | `/v1/x/search?q=&limit=10` | recent 検索 | 2,250 |
| POST | `/v1/x/verify/code` | 所有証明の認証コード発行（30 分有効・投稿文と intent URL 付き） | 0 |
| POST | `/v1/x/verify` | 所有証明の検証（作者一致 ∧ コード含有 ∧ @AICUai メンション。`status_url` を渡す） | 0 |

## 使いどころ・注意

- **引用カードの描画は無い**。`status/:id` で本文・著者・添付画像 URL（`media[]`）を取り、引用は自分で組む（出典 URL は x.com のものを添える）。動画は `media[].url` が mp4、サムネイルは `preview_image_url`。
- `status/:id` は X の公式 API が無い環境でも syndication 経由で動く（そのときは添付だけで、メトリクスは返らない）。
- **反応の数（いいね・リポスト・ブックマーク・返信・引用・表示）は `status/:id` が返す**（2026-09-28〜）。`bookmark_count` と `impression_count` は自分のポストにだけ付く。
- 同じ id を 10 分以内に再取得してもキャッシュから返る（課金なし）。
- レート制限は他 API と共通（429 `rate_limited`）。エラーの形は `{ "error": { "code", "message" } }`。
- 機械可読の仕様: https://api.aicu.ai/openapi.json（`/v1/x/*`）。

---
*AICU Inc.*