---
name: hairbook-imagine-api
description: Read and write Hairbook Imagine (creative batches, hero videos, staff videos, variants) through the signed API host. Use when an agent needs Imagine data or needs to start a generation request without a browser session.
metadata:
  service: https://imagine.hairbook.dev
  api-host: api.imagine.hairbook.dev
  cli-version: 0.1.0
---

# Hairbook Imagine signed API

`api.imagine.hairbook.dev` は Cloudflare Access の外にある。共有秘密ではなく、**登録済み ssh-ed25519 鍵の署名**で通す。

## セットアップ（人間の承認が1回必要）

```sh
curl -fsSL https://get.imagine.hairbook.dev/connect.sh | sh
```

1. `imagine connect` が `~/.ssh/id_ed25519` の公開鍵で承認待ちリクエストを作る
2. 表示された `https://imagine.hairbook.dev/keys?code=…` を Access にログインした人間が開き、`ssh-keygen -lf` の指紋と見比べて承認する
3. CLI が承認を検知して `~/.config/hairbook-imagine/config.json`（mode 600）を書く

鍵が無ければ先に `ssh-keygen -t ed25519 -C "$(hostname)" -f ~/.ssh/id_ed25519`。秘密鍵は端末から出ない。

## 使い方

```sh
imagine api GET /api/variants?limit=5
imagine api POST /hero-videos --body payload.json
cat payload.json | imagine api POST /batches --body -
imagine key list
```

- `-q` ステータスだけ / `-i` ヘッダーも出す / `--json` 整形して出す
- 失敗（HTTP 4xx/5xx）は終了コード 1
- 設定の上書き: `IMAGINE_API_HOST` / `IMAGINE_CONFIG` / `IMAGINE_KEY`

## 署名の契約（v1）

```text
v1
<METHOD>
<path?query>
<timestamp>
<nonce>
<sha256 hex of body>
```

`ssh-keygen -Y sign -n imagine-request` で署名し、次のヘッダで送る。実装は CLI が行うので、自作する場合だけ読む。

- `X-Imagine-Key`: `signing_key.id`（UUID）
- `X-Imagine-Timestamp`: Unix 秒（許容ずれ±60秒）
- `X-Imagine-Nonce`: 32〜64桁の小文字16進（同じ値は二度使えない）
- `X-Imagine-Signature`: SSHSIG の armored body
- `X-Imagine-Request: 1`: 非GETで必須

## 禁止・注意

- `Origin` か `Cookie` を持つリクエストは署名ホストで 401。ブラウザから叩かない
- 署名ホストは `/api/` 以外を返さない。管理系（鍵の発行・失効）は `https://imagine.hairbook.dev/keys` だけ
- 有料生成は依頼UUIDで管理する。同じUUIDの再送は状態確認、新しいUUIDで失敗runを自動再送しない
- 失敗・完了不明の run は課金状態を確認するまで再送しない（`docs/signed-requests.md`・画像/動画の各 docs を参照）