---
title: creative image
description: List image models and create image generation jobs.
canonical_url: https://orchestor.io/docs/en/cli/creative/image
markdown_url: https://orchestor.io/docs/en/cli/creative/image.md
contentType: reference
---

# creative image

`orc creative image` lists image models, returns one model's details, and creates image generation jobs. Generation is asynchronous: `image generate` returns `job.id`, and with `--wait` it waits for completion and prints the artifacts.

Check model IDs and inputs with `image models list`. Per-model inputs and pricing shapes are in [Models](https://orchestor.io/docs/creative/models.md).

## Usage

```bash title="terminal"
orc creative image generate --model gpt-image-2 --prompt "A red cube on a white background" --wait --json
```

*Generate an image, wait for it to finish, and print the artifacts.*

## Subcommands

### `models list`

画像モデルを一覧表示

```bash title="terminal"
orc creative image models list [options]
```

### `models get`

画像モデルを取得

```bash title="terminal"
orc creative image models get <model-id> [options]
```

### `generate`

画像を生成

```bash title="terminal"
orc creative image generate [options]
```

#### Unique options

##### `--idempotency-key`

同じ入力の再送で同じジョブを返すキー。1〜255 文字の印字可能 ASCII。同じキーで異なる入力を送ると 409 です。

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --idempotency-key <value>
```

##### `--model`

(required) カタログに掲載されたモデル ID を指定します。利用可能な入力と料金は、呼び出すワークスペースのカタログ行で確認してください。; enum: higgsfield-soul|soul-2.0|gpt-image-2.5|gpt-image-2.5-sunburst|gpt-image-2.6|gpt-image-2.6-sunburst|gpt-image-2|nano-banana-2.1|nano-banana-2-lite|nano-banana-2|ideogram-vector|ideogram-4-5-precise-edit|seedream-5.5|minimax-h3-image|flux-3-image|gpt-image-1.5|nano-banana-pro|seedream-5-lite|seedream-4-5-edit|grok-image|seedream-v4|flux-2-pro|flux-2-flex|ideogram-v3|recraft-v4|qwen-image-layered|qwen-image-angles|ideogram-v4.5|nano-banana|flux-kontext-max|wan-2.2|recraft-v4.1|seedream-5-flash|z-image|flux-2-max|kling-image-o1|kling-image-3-omni|seedream-5-pro|higgsfield-soul-standard|higgsfield-soul-cinema|grok-imagine-2|recraft-v4.1-utility|kling-image-3|higgsfield-ai-influencer|higgsfield-ads-studio

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --model <value>
```

##### `--prompt`

(required) 生成する内容、または編集で変更したい内容を記述する文章。

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --prompt <value>
```

##### `--character-element-id`

Soul 2 で使用する、このワークスペースの学習済みキャラクター要素の ID。

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --character-element-id <value>
```

##### `--image-urls`

編集や参照に使う画像の HTTPS URL。入力は認証なしで取得できる必要があります。; csv

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --image-urls <value>
```

##### `--mask-url`

編集する領域を指定するマスク画像の HTTPS URL。対応モデルで使用します。

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --mask-url <value>
```

##### `--aspect-ratio`

出力の幅と高さの比。auto は入力画像に合わせます。モデルの対応値を確認してください。; enum: auto|1:1|16:9|9:16|4:3|3:4|3:2|2:3|4:5|5:4|9:8|1:2|2:1|1:3|3:1|1:4|4:1|1:8|8:1|9:21|21:9|10:16|16:10|20:9|19.5:9|9:19.5|9:20|6:10|14:10|10:14

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --aspect-ratio <value>
```

##### `--image-size`

プリセット、WIDTHxHEIGHT、または width と height のオブジェクト。aspect_ratio より優先されます。

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --image-size <value>
```

##### `--quality`

モデルが受け付ける生成品質。対応する値はカタログで確認します。

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --quality <value>
```

##### `--resolution`

出力の解像度。モデルが対応する値をカタログで確認します。; enum: 0.5K|1K|2K|4K|720p|1080p

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --resolution <value>
```

##### `--num-images`

一つのジョブで生成する画像数。共通スキーマの範囲内でもモデル固有の上限が適用されます。

Type: `number`. Optional.

```bash title="terminal"
orc creative image generate --num-images <value>
```

##### `--output-format`

成果物のファイル形式。対応する値はモデルによって異なります。; enum: png|jpeg|jpg|webp|gif|svg

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --output-format <value>
```

##### `--metadata`

利用者の追跡用データ。ジョブと関連付けて保存し、モデルには送りません。; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --metadata <value>
```

##### `--mode`

async は即時応答、webhook は終端通知、sync と subscribe は時間を区切って完了を待ちます。; enum: async|sync|subscribe|webhook

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --mode <value>
```

##### `--webhook-url`

終端イベントを受け取る公開 HTTPS URL（2048 文字以内、既定のポート）。async または webhook モードで指定し、sync とは併用できません。localhost、プライベート、ループバック、リンクローカルのアドレス宛ては指定できません。ジョブが完了、失敗、取消のいずれかになると、ワークスペースの署名シークレットで署名した通知を 1 件送ります。; max 2048 chars

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --webhook-url <value>
```

##### `--wait-timeout-seconds`

HTTP 応答を待つ秒数。0〜30。時間を過ぎてもジョブは継続します。

Type: `number`. Optional.

```bash title="terminal"
orc creative image generate --wait-timeout-seconds <value>
```

##### `--project-id`

ジョブまたは配置先を関連付けるプロジェクトの ID。; max 200 chars

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --project-id <value>
```

##### `--model-params`

モデル固有設定。通常は省略または空オブジェクト。higgsfield-ai-influencer は tier（normal、freak、total）と selection（グループ ID から最大 4 個の選択 ID への対応）を指定できます。; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --model-params <value>
```

##### `--background`

GPT Image 2.5 系の背景指定。auto、transparent、opaque。対応モデルだけに指定します。; enum: auto|transparent|opaque

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --background <value>
```

##### `--rendering-speed`

生成速度と品質の配分。TURBO、BALANCED、QUALITY から対応モデルの値を選びます。; enum: TURBO|BALANCED|QUALITY

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --rendering-speed <value>
```

##### `--complexity`

描画前の計画量。low、medium、high。GPT Image 2.6 系で使用し、既定は high です。quality とは別の設定です。; enum: low|medium|high

Type: `string`. Optional.

```bash title="terminal"
orc creative image generate --complexity <value>
```

##### `--frame-count`

GIF のフレーム数。GPT Image 2.6 の GIF 出力で 2〜16、既定は 9。image_size は各フレームのサイズです。

Type: `number`. Optional.

```bash title="terminal"
orc creative image generate --frame-count <value>
```

##### `--frame-duration-ms`

GIF の 1 フレームの表示時間。20〜2,000 ミリ秒を 10 ミリ秒単位に丸めます。既定は 200。

Type: `number`. Optional.

```bash title="terminal"
orc creative image generate --frame-duration-ms <value>
```

## Examples

### List the available image models.

```bash title="terminal"
orc creative image models list --json
```

*List the available image models.*

### Check one model's inputs and pricing.

```bash title="terminal"
orc creative image models get gpt-image-2 --json
```

*Check one model's inputs and pricing.*

### Generate from a reference image.

```bash title="terminal"
orc creative image generate --model gpt-image-2 --prompt "Same composition in evening light" --image-urls https://example.com/input.png --wait
```

*Generate from a reference image.*

### Resend the same input safely.

```bash title="terminal"
orc creative image generate --model gpt-image-2 --prompt "A red cube on a white background" --idempotency-key render-001
```

*Resend the same input safely.*

## Permissions

Requires CLI authentication (`orc auth login` or `ORCHESTOR_API_KEY`) and access to the target Workspace. Creating a job requires write access.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc creative image`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)
- [`--wait`](https://orchestor.io/docs/cli/global-flags.md)
- [`--timeout`](https://orchestor.io/docs/cli/global-flags.md)
- [`--poll-interval`](https://orchestor.io/docs/cli/global-flags.md)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

[Documentation index](https://orchestor.io/docs/llms.txt)
