はじめに

manashiki-models は完全セルフサービスです。ブラウザを使うのは 2 回だけ — マジックリンクをクリックする時と、アップグレードで Stripe Checkout を開く時です。それ以外はすべて manashiki CLI または素の HTTP で完結します。

マジックリンクでサインイン — Web フォームまたは manashiki login。
組織を作成: manashiki orgs create <slug>。
staging キーを発行: manashiki keys create --env staging --name dev。
カタログを眺めるか GET /api/public/models を取得。
mk_test_* キーで staging からダウンロード — 月 10 回まで無料。
mk_live_* / mk_svc_* を発行する前に manashiki billing upgrade でアップグレード。
使用量は /dash/<slug>/usage で確認。

1. サインアップ / サインイン

パスワードはありません。/auth でメールアドレスを入力すると、マジックリンク (有効期限 15 分) が届きます。初回クリック時にアカウントが作成され、 14 日間有効なセッションが設定されます。マジックリンクのリクエストはメールアドレスごとに 1 時間あたり 5 回までに制限されています。

ターミナルからは、CLI がデバイスハンドシェイクと同じフローを使います。検証コードを表示し、リンクをメールで送り、クリックすると自動的にセッションを取得します。コードの有効期限は 10 分です。

# npm publish 準備中 — @manashiki/cli が npm に公開されるまでは
# 早期アクセスを依頼してください: contact@utakata-scifi.com
npm i -g @manashiki/cli
manashiki login --email you@example.com
# → 検証コードが表示され、メールのリンクをクリックすると CLI がサインインします。
# 認証情報は ~/.config/manashiki/credentials.json に保存されます

2. 組織を作成する

キー、モデル、課金、使用量はすべて組織に紐づきます。slug は ^[a-z0-9][a-z0-9-]{0,23}$ に一致する必要があり、すべての API キーに埋め込まれるため、平文で見えても問題ない名前を選んでください。作成者が org のオーナーになり、新しい org は Free tier から始まります。 org の作成はユーザーごとに 1 時間あたり 5 回までです。

manashiki orgs create my-app --name "My App"
# → 作成され、デフォルト org として選択されます
manashiki orgs list
manashiki orgs select my-app
manashiki orgs show my-app

HTTP では POST /v1/orgs に slug と省略可能な displayName を JSON ボディで送ります。認証はセッション (cookie manashiki_session または Authorization: Bearer <sessionToken>) です。 slug が使用済みの場合は 409 slug_taken が返ります。

3. API キーを発行する

キーには 4 種類あります。平文は作成時に一度だけ表示されるので、すぐに保存してください。キー一覧 API はハッシュ化されたレコードと表示用プレフィックスのみを返します。

プレフィックス	用途	デフォルトスコープ	プラン
`mk_pub_<slug>_…`	Publishable — 出荷するクライアントアプリへの埋め込み用 (漏えい前提で扱う)。読み取り / ダウンロードスコープのみ	`models:read`, `models:download`	Free
`mk_test_<slug>_…`	Staging での開発・テスト	`models:read`, `models:download`, `models:write`, `keys:read`, `usage:read`	Free
`mk_live_<slug>_…`	本番ダウンロード (ダウンロードごとに従量課金)	`models:read`, `models:download`, `models:download:live`	Paid
`mk_svc_<slug>_…`	エージェント / CI 向けのスコープ付きサービストークン。`expiresAt` が必須	作成時に指定。未指定なら `models:read`, `usage:read`	Paid

manashiki keys create --env staging --name dev
manashiki keys create --env pub --name embed
manashiki keys create --env production --name v1                       # 有償プランが必要
manashiki keys create --env svc --name ci --expires-at 2026-12-31T00:00:00Z   # 有償プランが必要
manashiki keys list
manashiki keys rotate <keyId>
manashiki keys revoke <keyId>

HTTP では POST /v1/orgs/<slug>/keys に kind として pub / test / live / svc のいずれかを指定します。Free の org で live または svc をリクエストすると 402 payment_required が返り、error.details に checkout URL が含まれます — 手順 6 を参照してください。 expiresAt なしの svc リクエストは 400 になります。

4. カタログを見る

カタログには first-party モデルと承認済みの community モデルが並びます。同じデータは匿名の HTTP でも取得でき、認証付きのエンドポイントでは自分の org のプライベートモデルも含まれます。

# 匿名: first-party + 承認済み community-public モデル
curl https://models.manashiki.com/api/public/models
curl https://models.manashiki.com/api/public/models/<modelId>

# 認証付き: 自分の org のプライベートモデルも含まれます
curl https://models.manashiki.com/api/models \
  -H "X-API-Key: mk_test_..."

キー認証のエンドポイントはすべて X-API-Key ヘッダーでキーを受け取り、カタログの読み取りには models:read スコープが必要です。

5. staging からモデルをダウンロードする

ダウンロードリクエストは署名付き URL (公開モデルでは 60 分有効) に加えて、クライアント側でアーティファクトを検証できるようオブジェクトの sha256 と size を返します。

curl https://models.manashiki.com/api/download/<modelId> \
  -H "X-API-Key: mk_test_..."
# → { "downloadUrl": "...", "sha256": "...", "size": 123456, "expiresIn": 3600 }

mk_test_* によるダウンロードは staging クォータにカウントされます: Free tier では月 10 ダウンロード。有償プランはローンチ時点では staging の上限を設けていません (1,000 回込み + 超過課金のモデルを計画中)。クォータを使い切ると、以降の staging ダウンロードは 402 payment_required と reason: "staging_quota_exceeded"、および checkout URL を返します — 何も黙って壊れることはありません。

6. 本番投入前にアップグレードする

mk_live_* と mk_svc_* の発行には有償プランが必要です。ゲートされた操作はすべて checkout URL 付きの 402 payment_required を返し、 CLI ならワンライナーで完結します。Developer プランは月額 $15 で、本番ダウンロード 1,000 回込み (以降は $0.001 / DL)。staging のダウンロードはローンチ時点では上限なしです — 料金を参照してください。

manashiki billing upgrade        # ブラウザで Stripe Checkout を開きます
manashiki billing status         # tier、staging 使用量、今期の live ダウンロード数
manashiki billing portal         # Stripe Customer Portal を開きます

# tier=paid になったら:
manashiki keys create --env production --name v1

支払いは Stripe webhook 経由で即時に反映されます — checkout 完了後、手動の手続きなしで live キーを発行できます。

7. 使用量を確認する

/dash/<slug>/usage のダッシュボードには、日次の時系列グラフと現在の期間のカウンターが表示されます。同じ数値は GET /v1/orgs/<slug>/usage/current と GET /v1/orgs/<slug>/usage/timeseries (セッション認証)、またはターミナルの manashiki billing status でも取得できます。

エージェント向けセットアップ (MCP)

公式 MCP サーバー @manashiki/mcp は、org・キー・モデル・課金・使用量の操作を Claude Code / Codex / Cursor / Devin に公開します。認証は MANASHIKI_API_KEY 経由の mk_svc_* キー (エージェントと CI に推奨)、またはローカル開発向けの MANASHIKI_SESSION_TOKEN を使います。

# npm publish 準備中 — @manashiki/mcp が npm に公開されるまでは
# 早期アクセスを依頼してください: contact@utakata-scifi.com
npm i -g @manashiki/mcp
MANASHIKI_API_KEY=mk_svc_... manashiki-mcp