tagru images

投稿案とは別に、AI で画像を作成（何もないところから）・編集（元の画像から）します。 TAGRU の画面の「画像作成」「画像編集」と同じ処理で、今月の上限（投稿案の画像と共通）も画面と同じものを使います。生成した画像は、手元のディレクトリに保存します。--save-as-asset --name <名称> を付けると、TAGRU に保存された画像をそのまま素材（tagru assets）にも登録します（画像を送り直しません）。

text

tagru images [quota] [--workspace <id>] [--target <prod|test|localhost>] [--json]
tagru images list [--limit <n>] [--cursor <id>] [--workspace <id>] [--target <prod|test|localhost>] [--json]
tagru images create --prompt <指示> [--aspect <1:1|3:4|4:3|9:16|16:9>] [--out <dir>] [--save-as-asset --name <名称>] [--yes] [--workspace <id>] [--target <prod|test|localhost>] [--json]
tagru images edit (<file> | --asset <asset-id>) [--prompt <指示>] [--aspect <1:1|3:4|4:3|9:16|16:9>] [--out <dir>] [--save-as-asset --name <名称>] [--yes] [--workspace <id>] [--target <prod|test|localhost>] [--json]
tagru images result <id> [--out <dir>] [--save-as-asset --name <名称>] [--workspace <id>] [--target <prod|test|localhost>] [--json]

サブコマンド

サブコマンド	内容
`quota`（省略可）	今月の残り枚数・使用数。`tagru images` は `tagru images quota` と同じです
`list`	画像の作成・編集の履歴（TAGRU の画面で作ったものも含む）を新しい順に表示する（上限は使わない）
`create`	指示（`--prompt`）から画像を 1 回作成する（書き込み・上限を 1 枚使う）
`edit`	元の画像（ファイルか素材）から画像を 1 回編集する（書き込み・上限を 1 枚使う）
`result <id>`	生成済みの画像を ID で受け取り直して保存する（上限は使わない）

オプション

オプション	内容
`--prompt <text>`	指示。`create` では必須、`edit` では任意
`<file>`	編集の元の画像（JPEG / PNG / WebP、10 MB 以下）。`edit` のみ。`--asset` とどちらか一方
`--asset <asset-id>`	編集の元の画像に使う素材の ID（`tagru assets` で確認。画像の素材だけ）。`edit` のみ
`--aspect <ratio>`	縦横比（`1:1` / `3:4` / `4:3` / `9:16` / `16:9`）。省略すると `3:4`
`--limit <n>`	`list` で 1 回に表示する件数（1〜24。既定は 20）
`--cursor <id>`	`list` の続き。前の一覧の最後に出た ID（`--json` では `nextCursor`）を渡す
`--out <dir>`	生成した画像を保存するディレクトリ（既定は今のディレクトリ。無いディレクトリは作りません）。`create` / `edit` / `result`
`--save-as-asset`	生成した画像を素材にも登録する（書き込み）。`--name` と一緒に指定する。`create` / `edit` / `result`
`--name <名称>`	素材の名称（30 文字まで。`tagru assets create --name` と同じ）。`--save-as-asset` のときだけ
`--yes`	生成前の確認を省く
`--workspace <id>`	ワークスペース（`tagru use` で保存した値より優先）
`-t, --target <name>`	接続先
`--json`	JSON で出力する

ワークスペースを選んでいない（tagru use も --workspace も無い）ときは、個人の画像として作成し、個人の上限を使います
--workspace は、そのコマンドだけに使います。tagru use で保存した選択は変わりません
--prompt などの値は - で始まっていても、そのまま値として受け取ります

作成・編集（create / edit）

bash

tagru images create --prompt "秋の新作ラテのポスター。暖色系で、文字は入れない" --aspect 4:3
tagru images edit ./photo.jpg --prompt "背景を白にして、商品を中央に"
tagru images edit --asset asset-0001 --prompt "ロゴを残して、背景を夜の街に"

生成の前に、今月の残り枚数を表示して確認します（[y/N]）。--yes で省けます。確認できない環境（標準入力が端末でない・AI エージェントからの実行）では --yes が無いとエラー（usage_error）になります
今月の上限に達しているとき・このプラン（または個人 / ワークスペース）で画像生成を使えないときは、生成せずにエラー（forbidden）で終わります。元の画像も送りません
編集の元の画像にファイルを指定すると、まずファイルを TAGRU に送り（生成ではないので上限は使いません）、続けて編集します。拡張子・サイズは送る前にも確かめます
生成には数十秒〜1 分ほどかかります。180 秒で打ち切ります。タイムアウト（network_error）でも、サーバーでは生成が続き、上限を使っていることがあります。すぐにやり直さず、tagru images list で作成者が「自分」・作成日時が実行した直後・指示が同じものを探し、状態が「完成」なら tagru images result <ID> で受け取ってください（「生成中」なら 1 分ほど待ってから確かめ直し、作成日時から 5 分たっても「生成中」のままなら確かめ直しをやめます）（下の「履歴（list）」を参照）
生成した画像は --out（既定は今のディレクトリ）に tagru-image-<ID>.jpg の名前で保存します（形式はサーバーが返したものに合わせます）。同じ名前のファイルがあるときは上書きせずにエラーになります
生成は済んだのに受け取り・保存で失敗したとき（同じ名前のファイルがある・通信が切れたなど）は、エラーに ID と tagru images result <ID> が出ます。生成し直さず、tagru images result <ID> で受け取り直してください（上限は使いません）。同じ --out で実行しても、保存済みの同じ画像は飛ばして残りだけを保存します
保存した画像をさらに直すときは、そのファイルを tagru images edit に渡します
編集でファイルを送ると、同じ中身の画像は 1 つだけ TAGRU に置きます（同じファイルで何度試しても増えません）
AI エージェントから使うときは、作業中のリポジトリに画像が混ざらないよう、--out で保存先（リポジトリの外のディレクトリなど）を指定してください
書き込みのコマンドです。読み取りだけのログインだと エラー（403）: この操作には書き込みの権限がありません。… になります。tagru login --write でログインし直し、同意画面で書き込みを許可してください
生成した画像は TAGRU にも保存され、画面で下書きにメディアを添付するときの一覧から選べます。下書きへの添付・投稿は TAGRU の画面から行ってください。素材として残したいときは --save-as-asset --name <名称> を付けます（下の「素材への登録」を参照）

素材への登録（--save-as-asset）

bash

tagru images create --prompt "秋の新作ラテのポスター" --save-as-asset --name "秋の新作ラテ"
tagru images result edit-0001 --save-as-asset --name "秋の新作ラテ"

生成した画像を、TAGRU に保存されたまま素材に登録します。手元のファイルを tagru assets create で送り直す必要はありません。素材は同じ個人 / ワークスペース（--workspace）に登録します
名称（--name）・20 件の上限・AI が説明を付けることは tagru assets create と同じです。名称が 30 文字を超えるときは送る前にエラー（usage_error）になります
create / edit は、生成の前に素材の空きを確かめます。素材が上限（20 件）に達しているときは、生成せずにエラー（forbidden）で終わります（今月の画像の上限は使いません）
画像は今までどおり --out にも保存し、素材にも登録して、登録した素材の ID を出します（tagru assets get <ID> で確認できます）
手元に保存できなかったとき（書き込めないディレクトリ・同じ名前のファイルがある・空き不足など）も、素材への登録は続けます。保存は失敗しているので終了コードは 1 ですが、エラーに「素材への登録は済んでいます: <素材の ID>」と出ます。同じコマンドをやり直さないでください（同じ画像の素材が増え、create / edit なら今月の上限も使います）。画像を受け取り直すときは --save-as-asset を付けずに tagru images result <ID> --out <dir> を実行してください
このとき --json では、標準エラー出力のエラーの横に item（create / edit / result の --json と同じ項目。assetIds に登録した素材の ID、files に保存できたファイル）を出します: {"error":{…},"item":{…,"assetIds":["asset-xxxx"]}}。item があれば、素材への登録は済んでいます
登録で失敗したとき（生成のあとに素材が上限になった・通信が切れたなど）は、エラーに画像の ID と tagru images result <ID> --save-as-asset --name <名称> が出ます。生成し直さずに、このコマンドで登録してください（上限は使いません）。通信が切れたときは、登録が済んでいることがあるので、先に tagru assets で確かめてください
画像のサイズ（10 MB 超）・形式で素材にできないときは、登録し直しても同じ結果になるため、この画像は素材に登録できません と出て、登録し直す案内は出しません。画像は TAGRU の画面のメディアの一覧から使えます
同じ画像を何度登録しても、そのたびに別の素材として追加されます
書き込みのコマンドです。result も --save-as-asset を付けると書き込みの権限が要ります

履歴（list）

bash

tagru images list
tagru images list --limit 5 --cursor edit-0005

画像の作成・編集の履歴を、作成日時の新しい順に表示します。CLI で作ったものも、TAGRU の画面で作ったものも出ます
1 回に表示するのは --limit 件（1〜24。既定は 20）です。続きがあるときは最後に tagru images list --cursor <ID> が出るので、同じ --limit を付けて実行します
状態は「完成」（画像があり、tagru images result <ID> で受け取れる）・「生成中」（まだ生成している。通常は 1 分ほどで終わり、作成日時から 5 分たっても生成中のままなら止まっている可能性があります。「停止」と出るのは 1 時間後です）・「停止（完成しません）」（生成中のまま止まっていて、もう完成しない）・「失敗」のどれかです。失敗・停止したものも今月の上限に数えます
作成者は「自分」・「他のメンバー」（ワークスペースで別の人が作ったもの）・「不明」（作った人を記録する前の古い履歴）のどれかです。個人の履歴はすべて「自分」です
生成の応答を待てずにタイムアウトしたときは、ここで作成者が「自分」・作成日時が実行した直後（作成日時はサーバーで生成を始めた時刻）・指示が同じものを探し、生成し直さずに tagru images result <ID> で受け取ってください
履歴を見るだけなので、上限は使いません。読み取りだけのログインでも使えます

text

$ tagru images list --limit 2
ワークスペース: (未選択。個人の履歴を表示します)
ID         作成日時          種類  状態    作成者  枚数  指示
edit-0002  2026-09-01 09:05  編集  完成    自分       1  背景を白にして、商品を中央に
edit-0001  2026-09-01 09:00  作成  生成中  自分       0  赤い車のポスター
続きがあります。`tagru images list --cursor edit-0001`（同じ --limit を付ける）で次を表示できます。

完成した画像は `tagru images result <ID> --out <dir>` で受け取れます（上限は使いません）。生成中のものは 1 分ほど待ってから確かめ直し、作成日時から 5 分たっても生成中のままなら、確かめ直しをやめてください（止まっている可能性があります）。

出力例

text

$ tagru images
ワークスペース: ws-xxxx
今月の残り: 7 / 10 枚
今月の使用数: 3

上限は投稿案の画像と共通で、翌月 1 日（UTC）に戻ります。

text

$ tagru images create --prompt "赤い車のポスター" --aspect 1:1
AI で画像を作成します（今月の残り: 7 / 10 枚。1 枚使います）。よろしいですか？ [y/N] y
ワークスペース: (未選択。個人の画像として作成します)
画像を作成しました。
ID: edit-0001
縦横比: 1:1
保存先: /path/to/tagru-image-edit-0001.jpg

さらに直すときは `tagru images edit <保存したファイル> --prompt <指示>` を実行してください。

text

$ tagru images result edit-0001 --save-as-asset --name "赤い車のポスター"
ワークスペース: (未選択。個人の画像を受け取ります)
生成した画像を保存し、素材に登録しました。
ID: edit-0001
保存先: /path/to/tagru-image-edit-0001.jpg
素材: asset-xxxx

確認の質問は標準エラー出力に出します。確認で取りやめると 画像を作成するのを取りやめました。 と出して終了コード 0 で終わります。

エラー

状況	表示（例）
今月の上限に達している（生成しない）	`今月の画像生成の上限（10 枚）に達しました。上限は翌月 1 日（UTC）に戻ります。`
このプラン・領域で使えない（生成しない）	`このプラン・領域では画像生成を利用できません。利用できるプランは TAGRU の画面で確認してください。`
生成の直前に上限に達した（サーバーの判定）	`エラー（403）: API の呼び出しに失敗しました（HTTP 403 image_limit_exceeded: …）。`
対応していない拡張子（送らない）	`対応していないファイル形式です: anim.gif（JPEG / PNG / WebP の画像を指定してください）。`
10 MB を超える・ファイルが無い（送らない）	`ファイルが大きすぎます: …` / `ファイルが見つかりません: ./photo.jpg`
画像でない素材（PDF など）	`画像の素材を指定してください（PDF などは元の画像に使えません）: asset-0002`
素材が見つからない	`エラー（404）: 素材が見つかりません: asset-9999（…）。`
中身が拡張子と違う（サーバーの判定）	`エラー（400）: …image_invalid_input…`
生成の失敗	`エラー（500）: …image_generation_failed…`
同じ名前のファイルがある	`保存先に同じ名前のファイルがあります（上書きしていません）: …`
保存先のディレクトリが無い	`保存先のディレクトリがありません: …`
生成の応答を待てずにタイムアウトした	`エラー: TAGRU のサーバーにタイムアウトしました（…）。サーバーでは生成が続き、今月の上限を使っていることがあります。すぐにやり直さず、\`tagru images list` で作成日時と指示から探し、…`
`list` の `--limit` が 24 を超える（送らない）	`--limit の上限は 24 です（指定値: 50）。続きは --cursor で読めます。`
`list` の `--cursor` の ID が無い	`エラー（400）: …image_invalid_input: cursor の履歴が見つかりません…`
`--save-as-asset` で素材が上限（生成しない）	`素材が上限の 20 件に達しているため、画像を生成せずに止めました（--save-as-asset）。…`
`--save-as-asset` の登録で素材が上限になった	`エラー: …HTTP 409 asset_limit_reached…。画像の生成は済んでいます（ID: edit-0001、…）。…\`tagru images result edit-0001 --save-as-asset --name <名称>` で素材に登録してください…`
`--save-as-asset` で画像が大きすぎる・形式が合わない	`エラー: …HTTP 413 asset_file_too_large…。画像の生成は済んでいます（…）。この画像は素材に登録できません（登録し直しても同じ結果になります）。…`
`--save-as-asset` で手元に保存できなかった（登録は済んだ。終了コード `1`、`--json` ではエラーの横に `item`）	`保存先に同じ名前のファイルがあります…。画像の生成は済んでいます（ID: edit-0001）。… 素材への登録は済んでいます: asset-xxxx。同じコマンドをやり直さないでください（…）。…`
`--name` だけ・`--save-as-asset` だけ（送らない）	`--name は --save-as-asset と一緒に指定してください（素材の名称です）。` / `--save-as-asset には、素材の名称を --name で指定してください。`

--json のときは、ほかのコマンドと同じく { "error": { "status", "code", "message" } } を標準エラー出力に出します（エラーと終了コード）。上限・プランのエラーの code は forbidden です。

`--json`

list は一覧の外枠（items）、それ以外は詳細の外枠（item）で出します。

tagru images quota --json:

json

{
  "target": "prod",
  "workspaceId": "ws-xxxx",
  "item": { "limit": 10, "used": 3, "remaining": 7 }
}

項目	型	内容
`limit`	number	今月の上限（このプラン・領域で使えないときは `0`）
`used`	number	今月の使用数（投稿案の画像と共通）
`remaining`	number	今月の残り

tagru images list --json:

json

{
  "target": "prod",
  "workspaceId": null,
  "items": [
    {
      "id": "edit-0002",
      "createdAt": "2026-09-01T09:05:00+09:00",
      "mode": "edit",
      "status": "done",
      "stalled": false,
      "mine": true,
      "imageCount": 1,
      "aspectRatio": "3:4",
      "prompt": "背景を白にして、商品を中央に"
    }
  ],
  "count": 1,
  "hasMore": true,
  "nextCursor": "edit-0002"
}

項目	型	内容
`id`	string	画像の作成・編集の ID（`tagru images result <id>` に渡す）
`createdAt`	string \| null	作成日時（ISO 8601。サーバーで生成を始めた時刻）
`mode`	string	`create`（作成）/ `edit`（編集）
`status`	string	`done`（完成）/ `processing`（生成中）/ `error`（失敗）
`stalled`	boolean	`processing` のまま止まっていて、もう完成しないか
`mine`	boolean \| null	自分が作ったか（個人は常に `true`。ワークスペースで作った人を記録する前の履歴は `null`）
`imageCount`	number	生成した画像の枚数（完成したものだけ 1 以上）
`aspectRatio`	string	縦横比
`prompt`	string	指示
`hasMore` / `nextCursor`	boolean / string \| null	続きがあるか、続きを読むときに `--cursor` に渡す値

tagru images result --json は { "id", "files", "assetIds" }（files は保存したファイルの絶対パス、assetIds は --save-as-asset で登録した素材の ID）です。

tagru images create --json / tagru images edit --json:

json

{
  "target": "prod",
  "workspaceId": null,
  "item": {
    "generated": true,
    "mode": "create",
    "id": "edit-0001",
    "aspectRatio": "1:1",
    "files": ["/path/to/tagru-image-edit-0001.jpg"],
    "assetIds": []
  }
}

項目	型	内容
`generated`	boolean	生成したか（確認で取りやめたら `false`）
`mode`	string	`create` / `edit`
`id`	string \| null	画像の作成・編集の ID（取りやめたら `null`）
`aspectRatio`	string \| null	生成に使った縦横比（取りやめたら `null`）
`files`	string[]	保存したファイルの絶対パス（取りやめたら空）
`assetIds`	string[]	`--save-as-asset` で登録した素材の ID（`tagru assets get <id>` に渡す。付けていない・取りやめたら空）

tagru images ​

サブコマンド ​

オプション ​

作成・編集（create / edit） ​

素材への登録（--save-as-asset） ​

履歴（list） ​

出力例 ​

エラー ​

--json ​

tagru images

サブコマンド

オプション

作成・編集（create / edit）

素材への登録（--save-as-asset）

履歴（list）

出力例

エラー

`--json`