letzai-api

LetzAI API 統合スキル

概要

AI 画像・動画の生成、編集、アップスケーリング、アセットのアップロード、カスタムモデル（LoRA）のトレーニングに LetzAI パブリック API を統合する方法を説明します。人物、オブジェクト、スタイル向けにカスタムトレーニングしたモデルは、プロンプト内で @modelname を使って参照します。

認証

• ベース URL： https://api.letz.ai
• 認証： Authorization: Bearer YOUR_API_KEY
• API キーの取得： letz.ai/subscription
• Swagger（正確な仕様）： api.letz.ai/doc — 機械可読な形式は /doc-json と /doc-yaml です

const headers = {
  'Content-Type': 'application/json',
  Authorization: `Bearer ${process.env.LETZAI_API_KEY}`,
};

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['LETZAI_API_KEY']}",
}

パブリック API とプライベート API を混同しないでください。 https://api.letz.ai は、ここで説明するパブリック開発者向け API です。https://private-api.letz.ai は LetzAI のウェブアプリを動作させるもので、ルート名（/upscales、/image_completions、/video-edits）が異なります。これらのルートはパブリック API では 404 を返します。

未知のフィールドの拒否

API はリクエストボディを厳密に検証します。スキーマにないフィールドを送信すると、400 が返されます。特に、POST /images には negativePrompt、seed、aspectRatio はありません。アスペクト比は width／height で指定します。

主なワークフロー

1. 画像生成 — POST /images

パラメーター	型	デフォルト	備考
prompt	string	—	必須です。 @modelname タグを含めることができます。
baseModel	string	アカウントのデフォルト	下記のモデル表を参照してください。
mode	string	モデルのデフォルト	解像度ティアです。使用できる値はモデルによって異なります。
width	int	1600	480～2160
height	int	1600	480～2160
quality	int	2	1～6
creativity	int	2	1～6
hasWatermark	bool	true
systemVersion	int	アカウントのデフォルト	2 または 3
hideFromUserProfile	bool	false
webhookUrl	string	—	ジョブ完了時に POST されます。
organizationId	UUID	—	所属する組織にクレジットを請求します。

画像モデル

mode は解像度ティアで、指定できる値はモデルごとに異なります。

モデル	baseModel	mode の値	クレジット（生成）	クレジット（編集）
Nano Banana Pro（Google）	gemini-3-pro-image	default（1K） · 2k（HD） · 4k	80 / 160 / 240	80 / 160 / 240
Nano Banana 2（Google）	nbf-inferencesh	default（1K） · 2k（HD） · 4k	40 / 80 / 160	50 / 100 / 150
Nano Banana 2 Lite（Google）	nano-banana-2-lite	default（1K）	20	25
Seedream 5 Pro（ByteDance）	seedream-5-0-pro	2k（HD） · 4k	80 / 160	80 / 160
Seedream 4.5（ByteDance）	seedream-4-5-251128	2k（HD） · 4k	80 / 160	80 / 160
Flux 2（Black Forest Labs）	flux2	1k · hd	60 / 120	60 / 120
GPT Image 2（OpenAI）	gpt-image-2	1k · hd · 4k	160 / 240 / 480	160 / 240 / 480
WAN 2.7 Image Pro（Alibaba）	wan-2-7-image-pro	1k · 2k	10	10

エイリアスも使用できます。たとえば、gemini-3-pro-image-preview は Nano Banana Pro として解決されます。価格を含む最新のモデルカタログは、letz.ai/docs/models.json にあります。

ワークフロー

1. POST /images
2. レスポンスから id を読み取ります
3. 3 秒ごとに GET /images/{id} をポーリングします
4. status === "ready" になったら、imageVersions.original を読み取ります

examples/image_generation.js を参照してください。

2. 動画生成 — POST /videos

パラメーター	型	備考
prompt	string	必須です。
originalImageCompletionId	UUID	以前に生成した LetzAI 画像をアニメーション化します。
imageUrl	string	公開画像 URL をアニメーション化します。
imageUrls	string[]	マルチフレーム：[0] = 最初のフレーム、[1] = 最後のフレームです。
prompts	object[]	マルチショットのストーリーボード（video-kling3）：[{ prompt, duration }]。
baseModel	string	任意です。通常は settings.mode で指定します。
width / height / resolution	number	出力サイズを任意で指定します。
settings	object	モデル、長さ、音声の設定（以下を参照）。
webhookUrl	string
hidePrompt	bool
organizationId	UUID

画像入力は任意です。テキストのみから動画を生成する場合は、originalImageCompletionId / imageUrl / imageUrls をすべて省略してください。

settings

フィールド	備考
mode	動画モデルのキーです。表を参照してください。
duration	秒数です。モデルで許可されている値の範囲に制限されます。
withSound	対応している場合、ネイティブ音声を有効にします。
highQuality	より高解像度の設定です。通常、料金が 2 倍になります。
resolution	1 秒あたりの料金が設定されたモデルでは、"720p"、"1080p"、"4k" を指定します。

動画モデル

settings.mode には video- が付いたキーを使用します。

モデル	settings.mode	長さ	クレジット
Google Veo 3.1	video-veo31	8 s（固定）	1500 · 音声ありの場合 ×2 · 1080p の場合 ×2
Kling V3	video-kling3	3–15 s	150 · 音声ありの場合 300
Kling V2.6	video-kling26	5 または 10 s	150 · 音声ありの場合 ×2 · 1080p の場合 ×2
WAN 2.5	video-wan25	5 または 10 s	110 · 1080p の場合 ×2（画像から動画への変換のみ）
Seedance 2.0	video-seedance2	4–15 s	1 秒あたり：480p で 105 · 720p で 210 · 1080p で 500 · 4K で 1000（音声は常にオン）
Seedance 2.0 Enterprise	video-seedance2-enterprise	4–15 s	Seedance 2.0 と同じです。organizationId が必要です。
Gemini Omni Flash	video-gemini-omni	3–10 s	1 秒あたり 100（音声は常にオン）

ワークフロー

1. POST /videos
2. GET /videos/{id} を 2～3 秒ごとにポーリングします
3. status === "ready" になったら、videoVersions.original を読み取ります

examples/video_generation.py を参照してください。

3. 画像編集 — POST /image-edits

パラメーター	型	備考
mode	string	必須です。 context（AI 編集）または skin（肌の修正）を指定します。
prompt	string	編集指示です。@modelname タグを含めることができます。
imageUrl	string	単一のソース画像 URL です。
inputImageUrls	string[]	複数の参照元画像です（実際には最大 9 枚）。
originalImageCompletionId	UUID	以前に生成した LetzAI 画像を編集します。
originalImageCompletionIds	UUID[]	複数の LetzAI 画像をソースとして使用します。
baseModel	string	画像生成と同じ識別子です。
settings	object	{ resolution, aspect_ratio, model }
imageCompletionsCount	int	生成するバリエーション数（1～5、既定値は 1）です。skin では使用されません。
mask	string	Base64 マスクです。レガシーのインペインティングのみで使用されます。
width / height	number	目標寸法です。
webhookUrl、organizationId、hidePrompt

settings:

• resolution："2k"（HD）または "4k"（Ultra HD）
• aspect_ratio："1:1"、"16:9"、"9:16"、"4:3"、"3:4"、"21:9"、"9:21"
• model：baseModel と同じ識別子です

ソースを 1 つ以上指定してください：imageUrl、inputImageUrls、originalImageCompletionId または originalImageCompletionIds。

トップレベルの baseModel を優先してください。 サーバー側のキュールーティングでは baseModel を参照し、 settings.model はワーカーに転送されます。両方に同じ値を設定するのが最も安全です。

ワークフロー

1. POST /image-edits
2. GET /image-edits/{id} を 3 秒ごとにポーリングします
3. status === "ready" になったら、generatedImageCompletion.imageVersions.original を読み取ります

mode: "in"（インペインティング）と mode: "out"（アウトペインティング）は非推奨です。context を使用してください。

4. アップスケーリング — POST /upscale

公開ルートは /upscale（単数形）です。/upscales は非公開の Web アプリルートであり、 ここでは 404 を返します。

パラメーター	型	デフォルト	備考
imageId	UUID	—	LetzAI の画像生成 ID です。
imageUrl	string	—	公開画像 URL です。imageId の代わりに使用します。独自のファイルをアップスケールするには、/user-assets 経由でアップロードし、返された imageUrl を渡してください。
mode	string	default	アップスケーラーモデル — 表を参照してください。
size	number	—	2～12。出力サイズ — 表を参照してください。
strength	number	1	1～5。
prompt	string	—	クリエイティブなアップスケーラー向けの任意の指示です。
webhookUrl、organizationId

mode	アップスケーラー	size → 出力	クレジット
nano-banana-pro	Google Gemini 3 Pro	4 → 1K · 8 → 2K · 12 → 4K	80 / 160 / 240
nano-banana-2	Google Gemini 3.1 Flash	4 → 1K · 8 → 2K · 12 → 4K	50 / 100 / 150
gpt-image-2	OpenAI GPT Image 2	4 → 1K · 8 → 2K · 12 → 4K	160 / 240 / 480
pruna	Pruna P-Image-Upscale	4 → 1 MP · 8 → 4 MP · 12 → 16 MP	20 / 40 / 80
default	LetzAI 独自モデル	—	20

ワークフロー

1. POST /upscale
2. 3 秒ごとに GET /upscale/{id} をポーリングします
3. status === "ready" になったら、imageVersions.original を読み取ります

5. 独自ファイルのアップロード — POST /user-assets

2 段階の署名付き S3 アップロードです。ローカルファイルを /image-edits、/videos、 /upscale に渡す前に、公開 URL を取得するために使用します。

1. { extension }（および任意の originalFilename、 mimeType、fileSize、caption、metadata、numberOfImages）を指定して POST /user-assets を実行します。
2. 返された uploadUrl に、対応する Content-Type ヘッダーを付けてファイルの生バイト列を PUT します。Authorization ヘッダーは不要です — URL にはすでに署名が付与されています。
3. その後、手順 1 のレスポンスに含まれる imageUrl からファイルにアクセスできます。

使用可能な extension の値：jpg、jpeg、png、gif、webp、mp4、webm、mov、 avi、mp3、wav、ogg、m4a、aac、flac。

POST /user-images は同じフローの旧式の画像・動画専用バリアントです。音声も受け付ける /user-assets の使用を推奨します。

examples/uploads_and_training.md を参照してください。

6. カスタム AI モデル（@modelname）

人物、オブジェクト、スタイル向けにトレーニングされたモデルです。画像または編集の プロンプト内でタグ付けできます：@john_doe on the beach at sunset。

一覧： GET /models — クエリパラメーターは page、limit、sortBy、sortOrder、search、 name、userId、username、class（person | object | style）、type、 description、privacy（public | private | licensed）、systemVersion、 isActive、status です。ページネーション情報はレスポンスヘッダー X-Total-Count、 X-Current-Page、X-Per-Page、X-Total-Pages で通知されます。

1 件取得： GET /models/{id}

新しいモデルのトレーニング： POST /models — これは API 経由で利用できます（Enterprise プラン）。

パラメーター	備考
name	必須です。英数字、_、. を使用でき、最大 50 文字です。@tag になります。
class	必須です。person | style | object
privacy	public | private | licensed
type	任意です。省略すると自動生成されます。
trainingDataUrls	公開画像 URL を 1～50 個指定します。先に /user-assets 経由でアップロードしてください。
trainingMode	例：default、slow
settings	例：["NO_ADULT_CONTENT", "NO_VIOLENCE"]
description、website、webhookUrl、organizationId	任意です。

トレーニングは自動的に開始されます。status が available になるまで GET /models/{id} をポーリングします。

管理： PATCH /models/{id}、DELETE /models/{id}、 PUT /models/{id}/thumbnail。

ワークフローの判断ツリー

画像を作成する → モデルテーブルから baseModel と mode を選択 → POST /images → GET /images/{id} をポーリング → imageVersions.original。

トレーニング済みモデルを使用する → GET /models?class=person で名前を検索 → プロンプトに @name を指定 → 通常どおり生成します。

画像を編集する → ソースを取得（URL、/user-assets へのアップロード、または LetzAI の生成 ID） → mode: "context" を指定して POST /image-edits → ポーリング → generatedImageCompletion.imageVersions.original。

動画を作成する → ソース画像は任意 → settings.mode に video-* キーを指定して POST /videos → ポーリング → videoVersions.original。

アップスケールする → imageId または imageUrl を指定して POST /upscale → ポーリング → imageVersions.original。

モデルをトレーニングする → /user-assets 経由で画像をアップロード → trainingDataUrls を指定して POST /models → GET /models/{id} をポーリングし、ステータスが available になるまで待ちます。

ステータスのポーリング

すべての生成エンドポイントは非同期です。POST は id を返すため、終端ステータスになるまで 対応する GET をポーリングします。

リソース	ステータス
画像	new · generating · ready · failed · interrupted · not_allowed · hidden
動画	new · generating · ready · saved · failed · interrupted
画像編集	new · generating · ready · saved · failed · interrupted
アップスケール	new · generating · ready · failed
モデル	new · pending · training · finished · available · failed

"in progress" というステータスはありません。処理中のジョブは generating を返します。 ready と saved は成功、failed、interrupted、not_allowed は終端エラーとして扱います。レスポンスには progress（0～100）も含まれ、生成中は base64 の previewImage も含まれます。

推奨間隔：画像／編集／アップスケールは 3 秒、動画は 2～3 秒です。本番環境のワークロードでは、ポーリングの代わりに webhookUrl を指定してください。

実装の全体像については、examples/polling_pattern.md を参照してください。

エラー処理

ステータス	意味	対処方法
400	パラメーターが無効、または本文に未知のフィールドがある	範囲を確認し、スキーマにないフィールドを削除します
401	キーがないか無効、または organizationId のメンバーではない	Authorization ヘッダーを確認します
402	クレジットが不足している	letz.ai/subscription でチャージします
404	リソースが見つからない、またはプライベート API のルートを使用している	ID と、api.letz.ai にそのパスが存在することを確認します
429	レート制限に達した	指数バックオフで再試行します
500	サーバーエラー	バックオフを使って再試行します

制限事項

• すべての生成は非同期です。ポーリングするか、Webhook を使用してください。
• 動画はモデルごとに課金されます。秒単位で課金されるモデルは、1080p／4K では高額になることがあります。
• mode の値はモデルごとに異なります。未対応のティアを指定すると、モデルのデフォルトにフォールバックします。
• Seedance 2.0 Enterprise では、メンバーになっている organizationId が必要です。
• API にアクセスするには、有料サブスクリプションが必要です。

クイックリファレンス：API エンドポイント

エンドポイント	メソッド	用途
/images	POST	画像を作成
/images	GET	画像を一覧表示／フィルタリング
/images/{id}	GET	画像のステータスと URL
/images/{id}/interruption	PUT	生成を停止
/images/{id}/privacy	PUT	{ privacy: "public" | "private" | "licensed" }
/images/{id}/prompt-privacy	PUT	プロンプトを一般公開で非表示／表示
/image-edits	POST	編集を作成
/image-edits	GET	編集を一覧表示
/image-edits/{id}	GET	編集のステータスと URL
/image-edits/{imageCompletionId}/mask	GET	レガシーのインペイントで使用されたマスク
/videos	POST	動画を作成
/videos	GET	動画を一覧表示
/videos/{id}	GET	動画のステータスと URL
/videos/{id}/privacy	PUT	動画のプライバシー設定を変更
/videos/{id}/prompt-privacy	PUT	プロンプトを一般公開で非表示／表示
/upscale	POST	アップスケールを作成
/upscale	GET	アップスケールを一覧表示
/upscale/{id}	GET	アップスケールのステータスと URL
/upscale/{id}	DELETE	アップスケールを削除
/models	GET	モデルを一覧表示
/models	POST	新しいモデルをトレーニング
/models/{id}	GET	モデルの詳細
/models/{id}	PATCH	モデルのメタデータを更新
/models/{id}	DELETE	モデルを削除
/models/{id}/thumbnail	PUT	サムネイルを設定
/user-assets	POST	署名付きアップロード URL を取得（画像／動画／音声）
/user-assets	GET	アップロードを一覧表示
/user-assets/{id}	GET / PATCH / DELETE	アップロードを管理
/user-images	POST / GET	レガシーの画像・動画専用アップロードフロー
/user-images/{id}	GET / DELETE	レガシーのアップロードを管理
/realtime/health	GET	リアルタイムゲートウェイのヘルスチェック

パブリック API にはありません（プライベートな Web アプリのルートのため、404 が返されます）：/upscales、 /video-edits、/image_completions、PUT /videos/{id}/interruption。

主なレスポンスフィールド

• 画像／アップスケール： imageVersions.original、imageVersions["1920x1920"]、imageVersions["640x640"]
• 編集： generatedImageCompletion.imageVersions.original（ソースは originalImageCompletion）
• 動画： videoVersions.original
• 処理中： progress（0～100）、previewImage（base64）、失敗時の statusDetail

モデルカタログ

LetzAI でサポートされている AI モデルの最新リストと、そのパラメーターおよびトークンコストを確認するには、必ず models.json ファイルを参照してください。

モデルカタログ（ライブ）： letz.ai/docs/models.json

追加リソース

• Swagger / OpenAPI： api.letz.ai/doc · /doc-json
• 開発者向けドキュメント： letz.ai/docs/api
• モデルカタログ（ライブ）： letz.ai/docs/models.json
• 詳細リファレンス： api_reference.md
• コード例： examples/
• プラットフォームの全機能を網羅した LetzAI ドキュメント： letz.ai/docs