はじめに

API ドキュメント

ogflow は日本語タイトルの折り返し処理に特化した OGP 画像生成 API です。BudouX と JIS X 4051 禁則処理を内蔵し、日本語が自然に折り返された 1200×630px の PNG をリクエスト一本で生成できます。

ベース URL

1https://ogflow.jp

エンドポイント一覧

メソッド	パス	認証	説明
GET	/og	必須	クエリパラメータで PNG を直接返す
POST	/og	必須	JSON ボディで生成し R2 URL を返す
GET	/demo/og	不要	認証なしのデモ（ウォーターマーク付き・30 req/分）
GET	/health	不要	ヘルスチェック

クイックスタート

5 分で始める

API キーを取得して、SDK をインストールするだけで Next.js などから OGP 画像を生成できます。

1. API キーを申し込む

こちらから申し込むと Stripe で安全に登録でき、即座に sk_ogflow_... 形式のキーが発行されます。

2. SDK をインストール

npm install @ogflow/sdk
# または yarn add / pnpm add @ogflow/sdk

SDK を使わず HTTP クライアントで直接リクエストすることもできます。

3. 画像を生成する

SDK を使う場合：

import { createOG } from '@ogflow/sdk';
const og = createOG({ apiKey: process.env.OG_API_KEY! });
const { url } = await og.generate({ title: '記事タイトル', theme: 'minimal' });

curl で直接使う場合：

curl --get --data-urlencode "title=記事タイトル" \
  -H "Authorization: Bearer $API_KEY" \
  "https://ogflow.jp/og?theme=minimal" -o og.png

日本語を URL クエリに直接含めると Cloudflare が 400 を返します。--data-urlencode を使ってください。POST /og や SDK は日本語をそのまま渡せます。

認証

API キー認証

サーバーサイドから使う場合に推奨する方式です。Authorization ヘッダーに Bearer トークンとして API キーを指定します。

1Authorization: Bearer sk_ogflow_...

curl の例

curl --get --data-urlencode "title=テスト" \
  -H "Authorization: Bearer $API_KEY" \
  "https://ogflow.jp/og?theme=minimal" -o og.png

API キーはサーバーサイドのみで使用してください。ブラウザや CMS テンプレートに埋め込む場合は Signed URL 方式を使用してください。

Signed URL 認証

API キーを露出させずに有効期限付きの URL を生成する方式です。HTML への直接埋め込みや CMS テンプレートでの利用に適しています。

URL 構造

1https://ogflow.jp/og?title=...&theme=...&exp={unix}&key={api_key}&sig={hmac}

パラメータ	説明
exp	有効期限（Unix タイムスタンプ）。最大 86400 秒（24 時間）先まで
key	API キー
sig	`HMAC-SHA256(apiKey, ソート済みクエリ文字列)` の hex 値。`sig` 自身は除外

SDK での生成（推奨）

const url = await og.url({
  title: '記事タイトル',
  theme: 'minimal',
  ttl: 3600, // 秒（最大 86400）
});
// → "https://ogflow.jp/og?title=...&exp=...&key=...&sig=..."

API リファレンス

GET /og

クエリパラメータで OGP 画像を生成し PNG を直接返します。R2 にキャッシュ済みの場合は Cloudflare が直配信します。

GET https://ogflow.jp/og?title=...&theme=...

リクエスト例

curl --get \
  --data-urlencode "title=記事タイトル" \
  --data-urlencode "siteName=My Blog" \
  -H "Authorization: Bearer $API_KEY" \
  "https://ogflow.jp/og?theme=minimal" -o og.png

レスポンスヘッダー

ヘッダー	値の例	説明
Content-Type	image/png
Cache-Control	public, max-age=31536000, immutable	キャッシュ済みの場合
X-OG-Cache	HIT \| MISS	R2 キャッシュの状態
X-OG-Generation-Ms	87	生成時間（ms）。MISS 時のみ

POST /og

JSON ボディで OGP 画像を生成し、R2 の永続 URL を返します。Webhook から事前生成したい場合や長いタイトルを URL エンコードせずに渡したい場合に使います。

POST https://ogflow.jp/og

リクエスト例

curl -X POST "https://ogflow.jp/og" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"記事タイトル","theme":"minimal","siteName":"My Blog"}'

レスポンス（200 OK）

{
  "url":    "https://pub-....r2.dev/og/minimal/abc123.png",
  "hash":   "abc123...",
  "cached": false
}

フィールド	型	説明
url	string	R2 の公開 URL（無期限）
hash	string	パラメータの SHA256 ハッシュ
cached	boolean	true の場合は既存画像を返した（再生成なし）

パラメータ一覧

GET はクエリパラメータ、POST は JSON ボディとして渡します。パラメータ名は共通です。

名前	必須	型	制約	説明
title	必須	string	1〜120 文字	OGP 画像のメインタイトル。BudouX + 禁則処理で自動折り返し
description	任意	string	最大 240 文字	タイトル下のサブテキスト（テーマによって表示文字数が切り詰められます）
theme	任意	enum	—	テーマ名。デフォルト: `minimal`。テーマ一覧参照
siteName	任意	string	最大 40 文字	サイト名。テーマによってヘッダーや右カラムに表示
size	任意	enum	`1200x630` \| `1200x600`	画像サイズ。デフォルト: `1200x630`
image	任意	string (URL)	`https://` から始まる URL	サムネイル画像 URL。テーマによってレイアウト内に表示
avatar	任意	string (Base64)	Base64 エンコード済み PNG	`zenn` テーマのみ有効。フッターに 48px 円形アバターを表示
exp	Signed URL 時必須	integer	Unix タイムスタンプ	有効期限。現在時刻から最大 86400 秒先まで
key	Signed URL 時必須	string	—	Signed URL で使用する API キー
sig	Signed URL 時必須	string	HMAC-SHA256 hex	署名値。SDK の `og.url()` が自動生成

レスポンス

GET /og — PNG 直接レスポンス

R2 にキャッシュ済みの場合（X-OG-Cache: HIT）は Cloudflare CDN から直配信されます。初回は Generator が生成して R2 に保存してからクライアントに返します。

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=31536000, immutable
X-OG-Cache: HIT

POST /og — JSON レスポンス

同じパラメータで 2 回呼ぶと cached: true が返り、再生成は行いません。

HTTP/1.1 200 OK
Content-Type: application/json
{ "url": "https://pub-....r2.dev/og/minimal/abc.png", "hash": "abc...", "cached": false }

TypeScript SDK

インストール

公式 TypeScript SDK @ogflow/sdk は Node.js 18+・Cloudflare Workers・ブラウザで動作します。ゼロランタイム依存で Web Crypto API のみを使用します。

npm install @ogflow/sdk
# または yarn add @ogflow/sdk / pnpm add @ogflow/sdk

初期化

import { createOG } from '@ogflow/sdk';
const og = createOG({
  apiKey: process.env.OG_API_KEY!,
  // baseUrl: 'https://ogflow.jp', // デフォルト値
});

og.generate()

POST /og を呼び出して画像を事前生成し、R2 の永続 URL を返します。Next.js の generateMetadata などサーバーサイドに最適です。

const { url, hash, cached } = await og.generate({
  title:       '記事タイトル',
  theme:       'minimal',
  description: '記事の概要テキスト',
  siteName:    'My Blog',
});
// url → "https://pub-....r2.dev/og/minimal/abc.png"

型定義

generate(params: OgParams): Promise<OgGenerateResult>
interface OgGenerateResult {
  url:    string;   // R2 の永続 URL
  hash:   string;   // パラメータの SHA256 ハッシュ
  cached: boolean;  // true = 再生成なし
}

og.url()

API リクエストを送らずに Signed URL を生成します。HTML への埋め込みや CMS テンプレートで URL を事前に確定させたい場合に使います。

const url = await og.url({
  title: '記事タイトル',
  theme: 'zenn',
  ttl:   3600 * 24, // 最大 24 時間（86400 秒）
});
// → "https://ogflow.jp/og?title=...&exp=...&key=...&sig=..."

og.url() は async 関数です（内部で Web Crypto API を使用）。必ず await してください。

型定義

url(params: OgUrlOptions): Promise<string>
interface OgUrlOptions extends OgParams {
  ttl?: number; // 有効期間（秒）。最大 86400
}

共通型

type Theme = 'minimal' | 'zenn' | 'dark' | 'gradient'
            | 'newspaper' | 'tweet' | 'bold' | 'note';
type Size  = '1200x630' | '1200x600';
interface OgParams {
  title:        string;
  description?: string;
  theme?:       Theme;
  size?:        Size;
  siteName?:    string;
}

エラー処理

API がエラーを返した場合、SDK は OgflowError を throw します。

import { createOG, OgflowError } from '@ogflow/sdk';
try {
  const { url } = await og.generate({ title: '...' });
} catch (err) {
  if (err instanceof OgflowError) {
    console.error(`HTTP ${err.status}: ${err.message}`);
    // err.status: 400 | 401 | 403 | 429 | 502
  }
}

連携ガイド

Next.js

App Router の generateMetadata で og.generate() を呼ぶことで、記事ごとに OGP 画像を自動生成できます。

// app/blog/[slug]/page.tsx
import { createOG } from '@ogflow/sdk';
const og = createOG({ apiKey: process.env.OG_API_KEY! });
export async function generateMetadata(
  { params }: { params: { slug: string } }
) {
  const post = await fetchPost(params.slug);
  const { url } = await og.generate({
    title:    post.title,
    theme:    'minimal',
    siteName: 'My Blog',
  });
  return {
    openGraph: { images: [{ url, width: 1200, height: 630 }] },
    twitter:   { card: 'summary_large_image', images: [url] },
  };
}

R2 にキャッシュ済みの場合（cached: true）は Generator への通信が発生しないため高速です。記事の初回公開時のみ生成コストがかかります。

microCMS 連携

記事公開時に Webhook を受けて OGP 画像を自動生成します。SDK 不要で、管理画面の設定だけで導入できます。

Step 1: ダッシュボードでプロジェクトを作成

ダッシュボード → プロジェクト → 新規作成からプロジェクト ID と Webhook シークレットを発行します。テーマとサイト名もここで設定します。

Step 2: microCMS 管理画面で Webhook を設定

URL:        https://ogflow.jp/webhooks/microcms
Header:     X-OG-Project-Id: {プロジェクト ID}
シークレット: {Webhook シークレット}

Webhook レスポンス

{
  "status":       "generated",
  "contentId":    "article-123",
  "permalinkUrl": "https://pub-....r2.dev/og/minimal/abc.png"
}

Webhook は同期処理です。Fly.io のコールドスタート中は 5〜10 秒かかることがありますが、microCMS のデフォルトタイムアウト（10〜30 秒）内には収まる想定です。

ogflow は microCMS の contents.new.title フィールドを参照します。フィールド名が title 以外の場合はダッシュボードの「タイトルフィールド」設定で変更できます（近日対応）。

リファレンス

テーマ一覧

theme パラメータで指定できるテーマの一覧です。Free プランでは minimal と zenn のみ利用できます。

theme	プラン	説明
minimal	Free	白背景・左寄せシンプルレイアウト。汎用的で多くのブログに合います
zenn	Free	濃紺背景・白文字。技術記事・Zenn スタイルのブログに
dark	Hobby+	ダーク背景・グラデーションアクセント。モダンな技術ブログ向け
gradient	Hobby+	紫→青のグラデーション背景。SNS でインパクトを出したい場合に
newspaper	Hobby+	新聞風・マストヘッド付き。メディア・ニュースサイト向け
tweet	Hobby+	左右カラム分割。左に本文・右にサイト名を大きく表示
bold	Hobby+	黒背景・中央太字・ラジアルグロー。コンテンツをドラマチックに見せる
note	Hobby+	Note 風・上部アクセントライン。柔らかい雰囲気のブログに

Free プランで minimal / zenn 以外を指定すると minimal にフォールバックします。Free プランの画像には右下に ogflow.jp のウォーターマークが入ります。

実際の表示はランディングページのデモで確認できます。

レート制限

全プランにレート制限が適用されます。超過すると 429 Too Many Requests が返ります。

プラン	レート上限	月間生成枚数
Free	60 req / 分	200 枚 / 月
Hobby	600 req / 分	5,000 枚 / 月
Pro	3,000 req / 分	30,000 枚 / 月

429 レスポンス

HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "error": "rate limit exceeded" }

R2 キャッシュ済みの画像（GET /og の X-OG-Cache: HIT）は Cloudflare CDN から直配信されるため、レート制限にカウントされません。同じパラメータでの再リクエストは実質無制限です。

エラーコード

HTTP ステータス	意味	よくある原因
400 Bad Request	パラメータ不正	`title` が空・120 文字超、存在しない `theme` 名など
401 Unauthorized	認証エラー	API キーが存在しない、Signed URL の `sig` が不正、`exp` 期限切れ
403 Forbidden	アクセス拒否	API キーが無効化されている、Free プランで利用できないテーマを指定した
429 Too Many Requests	レート制限超過 / 月間上限超過	プランのレート制限を超えてリクエストした、または月間生成枚数の上限に達した
502 Bad Gateway	Generator エラー	画像生成サーバー（Fly.io）への接続失敗。一時的なエラーなのでリトライを推奨

エラーレスポンス形式

1{ "error": "invalid theme" }