CMO AI Pro Developers
テンプレートツール
バナーテンプレートの登録、検索、AI解析を行う5つのツールの仕様です。
最終更新日：2026年8月26日
バナーテンプレートの登録、一覧取得、検索、AI解析に使う5つのツールです。
画像アップロードは2段階
テンプレート画像の登録は、prepare_banner_template_upload と confirm_banner_template_upload の 2ステップで行います。画像そのものはCMO AI Proのサーバーを経由せず、発行された署名付きURLへ 直接アップロードします。
1. prepare_banner_template_upload
↓ uploadUrl / storagePath / requiredHeaders を受け取る
2. 署名付きURLへ画像をPUT（CMO AI Proを経由しない）
↓
3. confirm_banner_template_upload
↓ サーバーが実サイズ・実形式・チェックサム・画像として開けるかを検証
テンプレートとして登録（status: collected）confirm を呼ぶまでテンプレートは作られません。途中でやめた場合、アップロード済みの画像は 一定期間後に削除されます。
prepare_banner_template_upload
組織専用の保存先への署名付きアップロードURLを発行します。この時点ではテンプレートは作られません。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
file_name | 文字列 | 必須 | — | 1〜200文字 |
content_type | 文字列 | 必須 | — | image/png / image/jpeg / image/webp |
size_bytes | 整数 | 必須 | — | 1〜12,582,912（12MiB） |
checksum_sha256 | 文字列 | 必須 | — | SHA-256を16進64文字で表記 |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
| フィールド | 内容 |
|---|---|
uploadUrl | アップロード先の署名付きURL |
storagePath | 保存先のパス。confirm に渡す |
expiresInSeconds | URLの有効期間（秒） |
requiredHeaders | アップロード時に付ける必要があるヘッダー |
declarations | 申告した内容（確認用） |
uploadUrl は機密情報として扱ってください。有効期間内であれば、URLを知る第三者が アップロードできます。
confirm_banner_template_upload
アップロードされた画像の実体を検証し、テンプレートとして登録します。申告した形式・サイズ・ チェックサムと実体が一致しない場合は登録されません。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
storage_path | 文字列 | 必須 | — | 1〜500文字。prepare が返した値 |
title | 文字列 | 任意 | — | 200文字以内 |
declared_content_type | 文字列 | 必須 | — | image/png / image/jpeg / image/webp |
declared_size_bytes | 整数 | 必須 | — | 1〜12,582,912（12MiB） |
declared_checksum_sha256 | 文字列 | 必須 | — | SHA-256を16進64文字で表記 |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
| フィールド | 内容 |
|---|---|
templateId | 登録されたテンプレートのID |
width | 画像の幅（ピクセル） |
height | 画像の高さ（ピクセル） |
status | collected（AI解析はまだ） |
エラー
| code | 発生条件 |
|---|---|
not_found | 指定パスに画像がアップロードされていない |
validation_error | 実体が申告内容または形式要件と一致しない、パスが利用できない |
登録直後の状態は collected です。バナー生成に使うには、次の start_template_analysis でテンプレート化する必要があります。
list_templates
組織のテンプレートと公式プリセットを表示順で取得します。公式プリセットが先、続いて組織の テンプレートが並びます。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
status | 文字列 | 任意 | — | collected / templating / templated / failed |
limit | 整数 | 任意 | 50 | 1〜100 |
応答
| フィールド | 内容 |
|---|---|
templates[].id | テンプレートID |
templates[].source | manual（組織）または preset（公式） |
templates[].isPreset | 公式プリセットか |
templates[].title | タイトル |
templates[].status | 状態。templated が利用可能 |
templates[].width | 幅（ピクセル） |
templates[].height | 高さ（ピクセル） |
templates[].genre | ジャンル |
templates[].createdAt | 作成日時 |
templates[].signedUrl | 画像の署名付きURL（1時間有効） |
バナー生成に使えるのは status が templated のテンプレートだけです。
search_templates
自然言語からテンプレートを類似検索します。組織のテンプレートと公式プリセットの両方が対象です。 クレジットは消費しません。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
query | 文字列 | 必須 | — | 2〜500文字 |
応答
| フィールド | 内容 |
|---|---|
results[] | list_templates と同じ項目に similarity を加えたもの |
results[].similarity | 類似度。高い順に並びます |
類似度が一定に満たないものは返りません。該当がない場合は空の配列が返ります。
検索結果は候補の提示であり、どのテンプレートを使うかはユーザーの指示に従って決めてください。
start_template_analysis
テンプレートのAI解析（テンプレート化）を開始します。完了は待ちません。 公式プリセットは対象外です。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
template_id | 文字列 | 必須 | — | UUID |
force | 真偽値 | 任意 | false | true で解析済みでも再実行 |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
| フィールド | 内容 |
|---|---|
jobId | ジョブID |
status | queued |
エラー
| code | 発生条件 |
|---|---|
not_found | テンプレートが存在しない、または組織外 |
validation_error | 公式プリセットを指定した、利用を終了したテンプレートを指定した |
conflict | 同じ対象の解析が実行中（jobId を含む）、または解析済み（force 未指定） |
payment_required | クレジット不足、または日次上限 |
消費
15クレジットです。