Getting started

manashiki-models is fully self-service. You touch a browser exactly twice: once to click a magic link, and once for Stripe Checkout if you upgrade. Everything else runs from the manashiki CLI or plain HTTP.

1. Sign in with a magic link — the web form or manashiki login.
2. Create an organization: manashiki orgs create <slug>.
3. Issue a test key: manashiki keys create --env test --name dev.
4. Browse the catalog or fetch GET /api/public/models.
5. Download with the mk_test_* key — 100 free test tokens per month.
6. Upgrade with manashiki billing upgrade before issuing mk_live_* / mk_svc_*.
7. Watch usage in /dash/<slug>/usage.

1. Sign up / sign in

There are no passwords. Enter your email at /auth and we send a magic link (valid 15 minutes). Clicking it creates your account on first use and sets a session that lasts 14 days. Magic-link requests are rate-limited to 5 per hour per email.

From a terminal, the CLI uses the same flow as a device handshake: it prints a verification code, emails you the link, and picks up the session automatically once you click through. The code expires after 10 minutes.

# npm publish pending — until @manashiki/cli is on npm,
# request early access: contact@utakata-scifi.com
npm i -g @manashiki/cli
manashiki login --email you@example.com
# → Verification code printed; click the emailed link; CLI signs in.
# Credentials are stored in ~/.config/manashiki/credentials.json

2. Create an organization

Keys, models, billing, and usage all hang off an organization. The slug must match ^[a-z0-9][a-z0-9-]{0,23}$ and is embedded in every API key, so pick something you are happy to see in plaintext. The creator becomes the org owner, new orgs start on the Free tier, and org creation is limited to 5 per hour per user.

manashiki orgs create my-app --name "My App"
# → created and selected as the default org
manashiki orgs list
manashiki orgs select my-app
manashiki orgs show my-app

Over HTTP this is POST /v1/orgs with a JSON body of slug and optional displayName, authenticated by your session (cookie manashiki_session or Authorization: Bearer <sessionToken>). A taken slug returns 409 slug_taken.

3. Issue API keys

There are four key kinds. The plaintext is shown exactly once at creation — store it immediately; listing keys only returns hashed records with a display prefix.

manashiki keys create --env test --name dev
manashiki keys create --env pub --name embed
manashiki keys create --env production --name v1                       # paid plan required
manashiki keys create --env svc --name ci --expires-at 2026-12-31T00:00:00Z   # paid plan required
manashiki keys list
manashiki keys rotate <keyId>
manashiki keys revoke <keyId>

The HTTP equivalent is POST /v1/orgs/<slug>/keys with kind set to one of pub / test / live / svc. Requesting live or svc on a Free org returns 402 payment_required with a checkout URL in error.details — see step 6. A svc request without expiresAt returns 400.

4. Browse the catalog

The catalog lists first-party models plus approved community models. The same data is available anonymously over HTTP, and an authenticated variant adds your org's private models.

# Anonymous: first-party + approved community-public models
curl https://models.manashiki.com/api/public/models
curl https://models.manashiki.com/api/public/models/<modelId>

# Authenticated: also includes your org's private models
curl https://models.manashiki.com/api/models \
  -H "X-API-Key: mk_test_..."

All key-authenticated endpoints take the key in the X-API-Key header and need the models:read scope for catalog reads.

5. Download a model with a test key

A download request returns a signed URL (valid 60 minutes for public models) plus the object's sha256 and size so your client can verify the artifact.

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

mk_test_* downloads count against the test-token allowance: 100 tokens per month on the Free tier, where one download costs ceil(model.size / 500MB) tokens. Paid plans keep going and meter overage. Once the allowance is exhausted, further test downloads return 402 payment_required with reason: "test_token_quota_exceeded" and a checkout URL — nothing breaks silently.

6. Upgrade before going to production

mk_live_* and mk_svc_* issuance is gated on a paid plan. Any gated action returns 402 payment_required with a checkout URL, and the CLI turns that into a one-liner. The Basic is $15 / month or $150 / year with 1,000 monthly live tokens; Pro is $60 / month or $600 / year with 5,000 monthly live tokens. Live overage is $0.001 / token and test/public overage is metered by token — see pricing.

manashiki billing upgrade        # opens Stripe Checkout in your browser
manashiki billing status         # tier, test/public/live tokens, live downloads
manashiki billing portal         # opens the Stripe Customer Portal

# Once tier=paid:
manashiki keys create --env production --name v1

Payment activates immediately via the Stripe webhook — after checkout completes, live key issuance works without any manual step.

7. Check usage

The dashboard at /dash/<slug>/usage shows a daily time-series graph and the current period's counters. The same numbers are available from GET /v1/orgs/<slug>/usage/current and GET /v1/orgs/<slug>/usage/timeseries (session auth), or from manashiki billing status in the terminal.

# npm publish pending — until @manashiki packages are on npm,
# request early access: contact@utakata-scifi.com
npm i -g @manashiki/cli
npm i @manashiki/sdk
npm i -g @manashiki/mcp

MANASHIKI_BASE_URL=https://models-staging.manashiki.com manashiki login
manashiki orgs create my-app
manashiki keys create --org my-app --env test --name dev
curl -H "X-API-Key: mk_test_..." \
  https://models-staging.manashiki.com/api/download/mediapipe-hand-landmarker-v0.10.9

# npm publish pending — until @manashiki/mcp is on npm,
# request early access: contact@utakata-scifi.com
npm i -g @manashiki/mcp
MANASHIKI_API_KEY=mk_svc_... manashiki-mcp