# Ideogram 4.5

> Ideogram 4.5 — text-to-image and drift-free iterative editing with up to 4 reference images and an optional mask.

## Overview

- **Model ID**: `ideogram-4-5`
- **Workflow**: `ideogram/v4.5/generate`
- **Provider**: Ideogram
- **Category**: Text → Image (image)
- **Output**: One or more image URLs.
- **Tags**: reference images, masked edit, 2k
- **Unified endpoint**: `POST https://api.picsart.com/workflows/v1/models/execute` (model id in the body)
- **Compatibility endpoint**: `POST https://api.picsart.com/workflows/ideogram/v4.5/generate/execute` (vendor's own parameters)
- **Execution**: sync (`/execute`) returns the result in one call; async is also available
- **Model page**: https://picsart.com/api-platform/models/ideogram-4-5

## Pricing

Rates are in USD. Every row below is an exact rate for the settings it names — the columns are the settings that change the price for this model. Every response reports what was actually charged in `response.usage.credits`.

| Tier | Use case | Rate |
| --- | --- | --- |
| Very low | Image → image | $0.002133 / generation |
| Very low | Text → image | $0.0088 / generation |
| Low | Any | $0.033 / generation |
| Medium | Any | $0.066 / generation |
| High | Any | $0.22 / generation |

Published rates. Volume pricing, invoicing and annual agreements: https://picsart.com/api-platform/contact-sales

## Authentication

The SDK and the REST API authenticate with a Picsart API key sent as a bearer token. Create a key in the console at https://picsart.com/api-platform/dashboard/api-keys, keep it in a server-side environment variable, and never ship it in browser code or commit it.

```bash
export PICSART_API_KEY="YOUR_KEY"
```

```http
Authorization: Bearer $PICSART_API_KEY
```

The CLI and the MCP server do not use an API key: `gen-ai login` signs in through the browser once per machine and stores a token locally.

## Interfaces

- **SDK** — `@picsart/ai-sdk` (TypeScript, Node 20+, ESM). Type-safe `ai.generate()` / `ai.generateText()` with per-model parameter types; polls long jobs for you.
- **REST** — the API gateway at `https://api.picsart.com`. Sync `/execute`, or async `/submit` + `/{taskId}/result`.
- **CLI** — `@picsart/gen-ai` (`gen-ai`). Generate from a terminal, quote cost before spending, emit JSON for pipelines.
- **MCP** — the same models inside Claude Code, Cursor, Windsurf and other MCP hosts. Setup: https://picsart.com/gen-ai-mcp/

```bash
npm install @picsart/ai-sdk      # SDK
npm install -g @picsart/gen-ai   # CLI (also drives the MCP server)
```

## Unified API (recommended)

One parameter set, used by the SDK and by REST alike: the names below are what `ai.generate('ideogram-4-5', …)` takes, and what goes inside the inner `params` of a REST call. Over REST the model id travels in the body, not the path — one workflow, `v1/models`, fronts the whole catalogue.

### Execution modes

- **Sync** — `POST /workflows/v1/models/execute` returns the result in one call. Only for jobs that finish within ~20 seconds; otherwise it times out.
- **Async** — `POST /workflows/v1/models/submit` returns a task id; poll `GET /workflows/v1/models/{taskId}/result` until `response.status` is `COMPLETED` or `FAILED`. Task statuses: `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `FAILED`.
- **SDK** — `ai.generate()` always awaits the finished result; polling is hidden.

### Input parameters

- **`prompt`** (`string`, _required_): Prompt
  - Max length: 10000 characters
- **`imageUrls`** (`list<string>`, _optional_): Images
  - Accepts: image URLs (max 5)
- **`mask`** (`string`, _optional_): Mask
  - Accepts: image URL
- **`aspectRatio`** (`string`, _optional_)
  - Default: `"auto"`
  - Options: `auto`, `source`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `8:5`, `5:8`, `2:1`, `1:2`, `3:1`, `1:3`
- **`resolution`** (`string`, _optional_)
  - Default: `"2K"`
  - Options: `1K`, `2K`
- **`magicPrompt`** (`string`, _optional_): Magic Prompt
  - Default: `"auto"`
  - Options: `auto`, `on`, `off`
- **`quality`** (`string`, _optional_)
  - Default: `"high"`
  - Options: `very_low`, `low`, `medium`, `high`
- **`count`** (`number`, _optional_)
  - Default: `1`
  - Options: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`
- **`seed`** (`number`, _optional_): Seed
  - Range: 0–2147483647 (step 1)
- **`enableCopyrightDetection`** (`boolean`, _optional_): Copyright Detection
  - Default: `false`

### Input JSON Schema

The inner `params` object. Over REST it is wrapped as `{ "params": { "model": "<id>", "params": <this> } }`; the SDK takes it directly.

```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 10000,
      "description": "Prompt"
    },
    "imageUrls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "image URL"
      },
      "maxItems": 5,
      "description": "Images"
    },
    "mask": {
      "type": "string",
      "format": "uri",
      "description": "Mask"
    },
    "aspectRatio": {
      "type": "string",
      "enum": [
        "auto",
        "source",
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "3:2",
        "2:3",
        "5:4",
        "4:5",
        "8:5",
        "5:8",
        "2:1",
        "1:2",
        "3:1",
        "1:3"
      ],
      "default": "auto"
    },
    "resolution": {
      "type": "string",
      "enum": [
        "1K",
        "2K"
      ],
      "default": "2K"
    },
    "magicPrompt": {
      "type": "string",
      "enum": [
        "auto",
        "on",
        "off"
      ],
      "default": "auto",
      "description": "Magic Prompt"
    },
    "quality": {
      "type": "string",
      "enum": [
        "very_low",
        "low",
        "medium",
        "high"
      ],
      "default": "high"
    },
    "count": {
      "type": "number",
      "enum": [
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        8
      ],
      "default": 1
    },
    "seed": {
      "type": "number",
      "minimum": 0,
      "maximum": 2147483647,
      "multipleOf": 1,
      "description": "Seed"
    },
    "enableCopyrightDetection": {
      "type": "boolean",
      "default": false,
      "description": "Copyright Detection"
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

The required parameters plus the defaults that shape the output, as a REST body:

```json
{
  "params": {
    "model": "ideogram-4-5",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "aspectRatio": "auto",
      "resolution": "2K"
    }
  }
}
```

### Response

The body is the gateway's status envelope: the output is at `response.result`, next to the task id, its status and the credits charged. Asset models return `url` plus an `items` array of results.

```json
{
  "status": "success",
  "response": {
    "id": "task_abc123",
    "status": "COMPLETED",
    "result": {
      "url": "https://cdn.picsart.com/…/result",
      "items": [
        {
          "url": "https://cdn.picsart.com/…/result"
        }
      ],
      "model": "ideogram-4-5"
    }
  }
}
```

What `ai.generate()` / `ai.generateText()` resolve to (the envelope already unwrapped):

```json
{
  "items": [
    {
      "url": "https://cdn.picsart.com/…/result"
    }
  ],
  "model": "ideogram-4-5"
}
```

### Usage examples

#### TypeScript (SDK)

```typescript
import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

const result = await ai.generate('ideogram-4-5', {
  prompt: "A serene mountain lake at golden hour, ultra detailed",
  aspectRatio: "auto",
  resolution: "2K"
});

console.log(result.url); // image URL
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v1/models/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "ideogram-4-5",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "aspectRatio": "auto",
      "resolution": "2K"
    }
  }
}'
```

#### CLI

```bash
gen-ai login  # once per machine
gen-ai models info ideogram-4-5  # this model's parameters
gen-ai pricing ideogram-4-5  # quote before spending credits
gen-ai generate -m ideogram-4-5 \
  -p "A serene mountain lake at golden hour" \
  --ar auto
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `ideogram/v4.5/generate` workflow takes Ideogram's own parameters exactly as the vendor defines them — nothing renamed or reshaped. It is the shortest path onto Picsart for request bodies already written against the vendor; the trade is that a request is written for one vendor, and the result comes back in the vendor's own shape. Same authentication.

- **Endpoint**: `POST https://api.picsart.com/workflows/ideogram/v4.5/generate/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('ideogram/v4.5/generate', params, { mode })` — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `prompt` | `string` | yes | — | The prompt. When images are given, refer to them by number ("image 1" is the source, "image 2"… are references). · max 10000 chars |
| `images` | `string[]` | no | — | Input image URLs. The first one is the source image to edit, the rest are references. At most 5 in total, or 4 with a mask. Omit for plain text-to-image. JPEG, PNG or WebP, at most 25 MB each, aspect ratio 1:6–6:1. · e.g. `["https://example.com/scene.png","https://example.com/jacket-reference.png"]` |
| `mask` | `string` | no | — | Mask URL for the first image. Must match its dimensions and contain black and white: black is edited, white is preserved. Requires images; aspect_ratio must be omitted. · e.g. `https://example.com/mask.png` |
| `aspect_ratio` | `string` | no | `auto` | Output aspect ratio (width:height), converted to an exact vendor size. "auto" (default) lets the vendor pick a 2K size from the prompt and images; "source" keeps the first image's own size (requires images). Must be omitted or "auto" with a mask. · Options: `auto`, `source`, `1:1`, `4:5`, `5:4`, `3:4`, `4:3`, `2:3`, `3:2`, `5:8`, `8:5`, `9:16`, `16:9`, `1:2`, `2:1`, `1:3`, `3:1` |
| `resolution` | `string` | no | `2K` | Output resolution tier for an explicit aspect ratio: 1K (up to 1024x1024 pixels) or 2K (up to 2048x2048). Ignored for "auto"/"source" and masked edits. · Options: `1K`, `2K` |
| `magic_prompt` | `string` | no | `auto` | Magic Prompt expansion. Use "off" for verbatim edit instructions. · Options: `auto`, `on`, `off` |
| `quality` | `string` | no | — | Rendering quality; higher takes longer and costs more. Defaults to medium with images and high without. very_low (fastest, cheapest) requires images. · Options: `very_low`, `low`, `medium`, `high` |
| `num_images` | `number` | no | `1` | Number of images to generate · 1–8 |
| `seed` | `number` | no | — | Random seed for reproducible results |
| `enable_copyright_detection` | `boolean` | no | — | Run copyright detection on the outputs. Adds latency; flagged images are dropped as unsafe. |
| `storage` | `object` | no | — | Optional storage details specifying where to copy the result file, if provided |
| └ `destination` | `string` | yes | — | Destination bucket name · e.g. `editing-temp` |
| `options` | `object` | no | — | Options controlling safety checks and drive integration |
| └ `safety_checks` | `object` | no | — | Safety check settings |
| └   `enabled` | `boolean` | no | — | Whether to run content moderation. Defaults to true. |
| └ `drive` | `object` | no | — | Save result to Picsart Drive |
| └   `name` | `string` | yes | — | File name in Picsart Drive |
| └   `attributes` | `object` | no | — | Custom attributes to attach to the file |
| └   `folder` | `object` | no | — | Target folder in Picsart Drive |

### Example request body

```json
{
  "params": {
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}
```

### Usage examples

#### TypeScript (`ai.apis.run`)

```typescript
import { createClient, ApiRunMode } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

// Calls the 'ideogram/v4.5/generate' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('ideogram/v4.5/generate', {
  prompt: "A serene mountain lake at golden hour, ultra detailed"
}, {
  mode: ApiRunMode.SYNC,
});

console.log(result); // workflow-specific output
console.log(usage?.credits); // amount charged, in $
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/ideogram/v4.5/generate/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}'
```

### Response

Over HTTP the vendor-shaped result arrives inside the gateway envelope at `response.result`:

```json
{
  "status": "success",
  "response": {
    "id": "wf_abc123",
    "status": "COMPLETED",
    "result": {
      "created": 0,
      "data": [
        {
          "seed": 0,
          "prompt": "…",
          "resolution": "…",
          "url": "https://cdn.picsart.com/…/result.jpg",
          "is_image_safe": true,
          "mimeType": "image/jpeg",
          "driveFile": {}
        }
      ],
      "generation_id": "wf_abc123",
      "seed": 0
    }
  }
}
```

`ai.apis.run()` unwraps that envelope and resolves to `{ result, usage }`:

```json
{
  "result": {
    "created": 0,
    "data": [
      {
        "seed": 0,
        "prompt": "…",
        "resolution": "…",
        "url": "https://cdn.picsart.com/…/result.jpg",
        "is_image_safe": true,
        "mimeType": "image/jpeg",
        "driveFile": {}
      }
    ],
    "generation_id": "wf_abc123",
    "seed": 0
  }
}
```

## Additional resources

- Model page: https://picsart.com/api-platform/models/ideogram-4-5
- Try it: https://picsart.com/api-platform/models/ideogram-4-5/playground
- SDK: https://picsart.com/api-platform/models/ideogram-4-5/sdk
- REST API (unified): https://picsart.com/api-platform/models/ideogram-4-5/api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/ideogram-4-5/advanced
- Pricing: https://picsart.com/api-platform/models/ideogram-4-5/pricing
- This document: https://picsart.com/api-platform/models/ideogram-4-5/llms.txt
- All models: https://picsart.com/api-platform/models
- Docs — quickstart https://picsart.com/api-platform/docs/quickstart, authentication https://picsart.com/api-platform/docs/authentication, SDK https://picsart.com/api-platform/docs/sdk, REST https://picsart.com/api-platform/docs/api-reference, CLI https://picsart.com/api-platform/docs/cli, MCP https://picsart.com/api-platform/docs/mcp
- CLI reference: https://picsart.github.io/picsart-mcp-cli-docs/guide/introduction