ドキュメント

サービス概要

Kirigami.ai は画像を「編集可能な」PowerPoint ファイルに変換する API です。スクリーンショットではなく、テキストは編集可能なまま、図形・レイアウト・背景も忠実に再現されます。

Kirigami.ai とは

AI が画像をベクトル化・セマンティックグループ化し、PowerPoint 上で図形を個別に編集できる .pptx を生成する API サービスです。アプリケーション・エージェント・スクリプトから REST / MCP / CLI のいずれかで呼び出せます。

アーキテクチャ

Kirigami.ai は 4 段階のパイプラインで信頼性とスケーラビリティを実現します:

STEP 01

Client

アプリケーション / エージェント / スクリプトが HTTP で REST API に送信。言語・プラットフォーム問わず HTTP が話せれば動作します。

STEP 02

API Gateway

認証（X-Api-Key）、プラン別レート制限、Zod によるバリデーション、初期ジョブ作成を担当します。

STEP 03

Durable Queue

ジョブのメタデータは Convex、大きなペイロードは R2 に保存。QStash が各画像を非同期で処理します。

STEP 04

Workers & Output

ベクトル化 → OCR → テキスト除去 → セマンティックグループ化 → PPTX 生成。完成した .pptx は署名付き URL で配信されます。

エンドポイント一覧

Method	Path	用途
`POST`	`/api/v1/upload`	画像アップロード
`POST`	`/api/v1/convert`	変換ジョブ開始
`GET`	`/api/v1/jobs/:jobId`	ジョブ状態取得
`GET`	`/api/v1/marketplace`	ギャラリー一覧
`GET`	`/api/v1/marketplace/:itemId`	ギャラリー詳細
`POST`	`/api/v1/publish`	ギャラリー投稿
`POST`	`/api/v1/auth/start`	CLI ログイン開始
`POST`	`/api/v1/auth/approve`	CLI 承認 (ブラウザ)
`GET`	`/api/v1/auth/poll/:sessionId`	CLI ポーリング
`POST`	`/api/v2/decompose`	画像のレイヤー分解
`POST`	`/api/v2/html-to-pptx`	HTML/CSS から PPTX 生成
`POST`	`/api/mcp`	リモート MCP (JSON-RPC)

はじめに

クイックスタート

3 分で最初の 1 枚を PPTX に変換してダウンロードするまでの手順です。

1. API キーを発行

設定 → API キーから新しいキーを作成してください。ip2p_ で始まる 64 文字が 1 度だけ表示されます（安全な場所にコピー）。

2. 画像をアップロード

curl -X POST https://kirigami.ai/api/v1/upload \
  -H "X-Api-Key: ip2p_YOUR_KEY" \
  -F "image=@/path/to/slide.png"

3. 変換を開始

curl -X POST https://kirigami.ai/api/v1/convert \
  -H "X-Api-Key: ip2p_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [{ "url": "<R2_URL>", "id": "img-1" }],
    "filename": "deck.pptx"
  }'

4. ステータスをポーリング

curl https://kirigami.ai/api/v1/jobs/YOUR_JOB_ID \
  -H "X-Api-Key: ip2p_YOUR_KEY"

status が completed になると downloadUrl が含まれます。3 秒間隔のポーリングが目安。

Node.js クライアント例

const KEY = process.env.KIRIGAMI_API_KEY!;
const BASE = "https://kirigami.ai";

// upload → convert → poll
const up = await fetch(BASE + "/api/v1/upload", {
  method: "POST",
  headers: { "X-Api-Key": KEY },
  body: form,
}).then((r) => r.json());

const { jobId } = await fetch(BASE + "/api/v1/convert", {
  method: "POST",
  headers: { "X-Api-Key": KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    images: [{ url: up.imageUrl, id: up.imageId }],
  }),
}).then((r) => r.json());

while (true) {
  const s = await fetch(BASE + "/api/v1/jobs/" + jobId, {
    headers: { "X-Api-Key": KEY },
  }).then((r) => r.json());
  if (s.status === "completed") console.log(s.downloadUrl);
  if (s.status === "failed") throw new Error(s.errorMessage);
  await new Promise((r) => setTimeout(r, 3000));
}

はじめに

認証

Kirigami.ai API は X-Api-Key ヘッダによる認証を使います。CLI 向けには OAuth ライクのデバイスコードフローも提供しています。

API キーの発行

形式: ip2p_ + 64 hex chars
ユーザーあたり最大 5 キー
保存は SHA-256 ハッシュのみ。漏洩時はダッシュボードで即時失効可能

リクエストに付ける

curl https://kirigami.ai/api/v1/jobs/YOUR_JOB_ID \
  -H "X-Api-Key: ip2p_xxxxxxxx..."

キーの取り扱い

環境変数に保管（ソースにハードコードしない）
フロントエンドに埋め込まない
漏洩したらダッシュボードで即失効する

認証エラー

HTTP	code	意味
401	`missing_api_key`	X-Api-Key ヘッダが無い
401	`invalid_api_key`	形式不正または失効
402	`insufficient_credits`	クレジット不足

コアコンセプト

ジョブ

変換処理は非同期ジョブとして実行されます。/convert で投入し、/jobs/:jobId でステータスをポーリングします。

ライフサイクル

pending → waiting_images → processing → completed
                                           └→ failed (クレジット返却)

status	意味	次のアクション
`pending`	キュー投入直後	ポーリング継続
`waiting_images`	画像処理待ち	ポーリング継続
`processing`	PPTX 組み立て中	ポーリング継続
`completed`	完了	`downloadUrl`
`failed`	恒久失敗	`errorMessage`

コアコンセプト

クレジット

変換はクレジット制です。1 枚あたり 10 クレジットを消費し、ジョブが失敗すれば自動返却されます。

アクション	消費
画像 1 枚の変換	10 credits
画像 50 枚の一括変換	500 credits
アップロード / ポーリング / マーケット閲覧	無料

クレジット不足時

// HTTP 402
{
  "success": false,
  "code": "insufficient_credits",
  "balance": 40,
  "required": 100,
  "shortage": 60
}

コアコンセプト

レート制限

全エンドポイントにレート制限があります。超過時は HTTP 429 と Retry-After ヘッダを返します。

エンドポイント	制限
`POST /convert`	10 / 分
`POST /upload`	20 / 分
`GET /jobs/:jobId`	60 / 分
`GET /marketplace`	20 / 分
`GET /marketplace/:itemId`	30 / 分
`POST /publish`	5 / 分
`POST /auth/start`	10 / 10分
`GET /auth/poll/:id`	120 / 10分

レスポンスヘッダ

X-RateLimit-Limit — 上限
X-RateLimit-Remaining — 残り
X-RateLimit-Reset — リセットまでの秒数
Retry-After — 429 の際のみ

コアコンセプト

エラーコード

全エンドポイントが共通の形式 { success: false, error, code, ...meta } を返します。

code	HTTP	説明
`missing_api_key`	401	X-Api-Key ヘッダが無い
`invalid_api_key`	401	不正または失効
`session_expired`	410	CLI セッション期限切れ
`too_many_keys`	422	5 個まで
`invalid_request`	400	Zod バリデーション失敗
`invalid_json`	400	JSON パース失敗
`rate_limited`	429	レート制限超過
`insufficient_credits`	402	クレジット不足
`job_not_found`	404	ジョブ未検出
`item_not_found`	404	アイテム未検出
`ng_word_detected`	400	禁止ワード検出
`internal_error`	500	予期しないサーバーエラー

API Reference

エンドポイント詳細

各エンドポイントのリクエスト/レスポンス形式・レート制限・エラー。

POST /api/v1/convert

POSThttps://kirigami.ai/api/v1/convert

1〜50 枚の画像をまとめて 1 つの PPTX に変換するジョブを投入します。jobId が返るのでポーリングで結果を取得。

リクエスト

{
  "images": [{ "url": "<R2_URL>", "id": "img-1" }],
  "filename": "deck.pptx",
  "removeText": true
}

レスポンス

{
  "success": true,
  "jobId": "conv_abc123...",
  "estimatedCredits": 10,
  "totalImages": 1,
  "queuedImages": 1,
  "processingMode": "qstash"
}

GET /api/v1/jobs/:jobId

GEThttps://kirigami.ai/api/v1/jobs/:jobId

ジョブのステータスを取得。

完了時のレスポンス

{
  "success": true,
  "status": "completed",
  "progress": 100,
  "downloadUrl": "https://...signed.url...",
  "completedAt": 1713000120000
}

POST /api/v1/upload

POSThttps://kirigami.ai/api/v1/upload

画像を R2 に保存し、変換用の署名付き URL を返します。JSON(base64) / multipart 両対応。

curl -X POST https://kirigami.ai/api/v1/upload \
  -H "X-Api-Key: ip2p_..." \
  -F "image=@slide.png"

制限

サイズ: 10 MB まで
MIME: image/png, image/jpeg, image/webp, image/gif

Marketplace

GEThttps://kirigami.ai/api/v1/marketplace

公開スライド一覧。

GEThttps://kirigami.ai/api/v1/marketplace/:itemId

スライド詳細（view 記録あり）。

POST /api/v1/publish

POSThttps://kirigami.ai/api/v1/publish

ギャラリーに下書き投稿。事前に /upload で画像を上げておく。

{
  "title": "My deck",
  "description": "...",
  "previewImageUrls": ["https://..."],
  "tags": ["business"]
}

CLI Auth

CLI ツールが API キーをハードコードせずに受け取るための 3 段階フロー:

POSThttps://kirigami.ai/api/v1/auth/start

POSThttps://kirigami.ai/api/v1/auth/approve

GEThttps://kirigami.ai/api/v1/auth/poll/:sessionId

start でセッション開始 → ブラウザ承認 → poll で 1 回だけキーを受け取る。

OpenAPI

対話式リファレンス

全エンドポイントを OpenAPI 3.1 で配信しています。Postman / Insomnia にインポートできます。

/api/openapi.json から仕様書を取得できます。

ブラウザで閲覧・試用する対話式 UI は下記: API リファレンス (Scalar)

ツール

CLI ガイド

ターミナルから画像を PPTX に変換。ブラウザ経由でキーを発行するので、キーレスで動かせます。

インストールとログイン

npm install -g @kirigami/cli
kirigami login     # ブラウザが開いて承認

基本的な使い方

kirigami convert slide.png --output deck.pptx
kirigami convert slides/*.png --output pack.pptx
kirigami status conv_abc123
kirigami publish deck.pptx --title "My pitch" --tags business

CI/CD

export KIRIGAMI_API_KEY=ip2p_...
kirigami convert slide.png --output deck.pptx

ツール

MCP ガイド

Claude Desktop / Claude Code / Cursor などの MCP 対応クライアントから、Kirigami のツールに直接アクセスできます。stdio とリモート HTTP の 2 経路に対応。

ツール一覧

ツール名	用途
`kirigami_decompose_image`	画像をレイヤー分解し、署名付き URL を返す
`kirigami_html_to_pptx`	HTML/CSS を編集可能 PPTX に変換
`kirigami_get_usage`	クレジット残高を取得

リモート MCP (推奨)

ワンライナーで接続できます。初回はブラウザが自動で開き、kirigami.ai にログイン → 「許可」をクリックするだけ。API キーの手動コピーは不要です。

POST/api/mcp

Claude Code / Claude Desktop / Cursor

claude mcp add --transport http kirigami https://kirigami.ai/api/mcp

クライアントが OAuth 2.0 (PKCE) を自動で実行し、認可コードと引き換えに kirigami の API キーを取得して保存します。発行されたキーは kirigami.ai/settings/api-keys に「MCP: <クライアント名>」として表示されます。

手動 config (古いクライアント向け)

OAuth 自動フローに対応していないクライアントは、API キーを直接 Bearer ヘッダで渡せます。

{
  "mcpServers": {
    "kirigami": {
      "type": "http",
      "url": "https://kirigami.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ip2p_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

OAuth フローの仕組み

クライアントが /api/mcp を未認証で叩く
401 + WWW-Authenticate で OAuth metadata を案内
.well-known/oauth-authorization-server から認可エンドポイントを取得
ブラウザで /oauth/authorize を開き、ユーザーが「許可」をクリック
/api/oauth/token で認可コードと PKCE verifier を交換 → API キー取得
以降のリクエストは取得した API キーを Bearer で送信

ローカル MCP (stdio)

リポジトリに同梱された Node.js スクリプトを直接起動する方式。完全ローカル動作なので、業務環境で外部接続を絞っている場合に向いています。

{
  "mcpServers": {
    "kirigami": {
      "command": "node",
      "args": ["/absolute/path/to/kirigami/mcp/kirigami-mcp-server.mjs"],
      "env": {
        "KIRIGAMI_API_KEY": "ip2p_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

動作確認

KIRIGAMI_API_KEY=ip2p_xxx node ./mcp/kirigami-mcp-server.mjs <<< \
  '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

どちらを選ぶか

通常はリモート MCP で十分です。ローカル stdio は (a) MCP リクエストを社外に出したくない、(b) 接続テストや自動化スクリプトの中で固定パスから起動したい、といった用途で使います。

ツール

Skills ガイド

Claude Code / Claude Desktop で配布される .skill パッケージ。エージェントが自動で呼び出すワークフローです。

提供している Skill

Skill	ユースケース	クレジット
`kirigami`	画像をそのまま PPTX に変換	10 / 画像
`kirigami-html`	Claude が HTML を生成して新しいスライドを設計 → PPTX 化	5 / PPTX 生成、5 / 画像分解

セットアップ

Skill ファイル (.skill) を Claude Code / Desktop に追加し、初回ログイン後はキー保存なしで動作します。

# 1. Skill をインポート (Claude Code)
claude skill add kirigami.skill
claude skill add kirigami-html.skill

# 2. 初回ログイン
python3 skills/kirigami/scripts/convert.py --login

# 3. あとは自然言語で
#    "この画像を PPTX にして"           -> kirigami
#    "東京の桜の名所スライド作って"      -> kirigami-html

両 Skill は認証を共有

kirigami と kirigami-html は ~/.kirigami/config.json を共有します。一度ログインすれば両方使えます。

ツール

変更履歴

API のバージョン履歴。Breaking な変更はメジャーバージョンを上げます。

v1.1.0 — 2026-04-26

POST /api/v2/decompose を追加 (画像のレイヤー分解、5 クレジット/画像)
POST /api/v2/html-to-pptx を追加 (HTML/CSS → 編集可能 PPTX、5 クレジット)
POST /api/mcp でリモート MCP を提供
ローカル MCP stdio サーバーを mcp/kirigami-mcp-server.mjs で同梱
新 Skill kirigami-html を追加 (HTML 駆動デザインフロー)
kirigami webapp 内部利用は POST /api/html-to-pptx で無料

v1.0.0 — 2026-04-22

公開 API v1 正式リリース
全エンドポイント Zod 契約化
全ルートにレート制限適用
エラーメッセージを日英 i18n 対応
OpenAPI 3.1 を /api/openapi.json から配信
Scalar による対話式リファレンス