# Marketing Studio Image

> Generate and edit Marketing Studio images with GPT Image 2.5 Flare.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/marketing-studio/image/flare`
- **Model ID**: `marketing-studio/image/flare`
- **Category**: image_edit, text2image
- **Kind**: inference
- **Tags**: featured, trending

## Pricing

Per 1M tokens: text input $5, cached text input $1.25, text output $10; image input $8, cached image input $2, image output $30. Quality defaults to high. Final cost uses actual token usage and standard credit rounding. The initial charge is an estimate reconciled on completion.

## Authentication

Keep credentials in server-side environment variables. The SDKs accept the same `KEY_ID:KEY_SECRET` value under their documented variable names.

```bash
export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL
```

The official SDKs configure the authorization header. Keep credentials server-side; the TypeScript SDK blocks browser use.

## API Information

Use `subscribe` to submit the model request and wait for a terminal result. TypeScript performs automatic polling with `withPolling: true`; Python's synchronous `subscribe` call also waits.

### Input Parameters

- **`prompt`** (`string`, _required_):
  Write your prompt here

- **`quality`** (`string`, _optional_):
  - Default: `"high"`
  - Options: `low`, `medium`, `high`, `xhigh`, `max`

- **`preset_id`** (`string`, _optional_):

- **`image_urls`** (`list<string>`, _optional_):

- **`moderation`** (`string`, _optional_):
  - Default: `"auto"`
  - Options: `auto`, `low`

- **`resolution`** (`string`, _optional_):
  - Default: `"2k"`
  - Options: `1k`, `2k`, `4k`

- **`aspect_ratio`** (`string`, _optional_):
  - Default: `"auto"`
  - Options: `auto`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`

- **`enhance_prompt`** (`boolean`, _optional_):
  - Default: `false`

### Input JSON Schema

```json
{
  "type": "object",
  "allOf": [
    {
      "if": {
        "required": [
          "enhance_prompt"
        ],
        "properties": {
          "enhance_prompt": {
            "const": true
          }
        }
      },
      "then": {
        "required": [
          "preset_id",
          "image_urls"
        ],
        "properties": {
          "image_urls": {
            "maxItems": 2,
            "minItems": 1
          }
        }
      }
    }
  ],
  "title": "GPT Image 2.5 Flare",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "title": "Prompt",
      "maxLength": 5000,
      "minLength": 1,
      "description": "Write your prompt here"
    },
    "quality": {
      "enum": [
        "low",
        "medium",
        "high",
        "xhigh",
        "max"
      ],
      "type": "string",
      "title": "Quality",
      "default": "high"
    },
    "preset_id": {
      "type": "string",
      "title": "Preset ID",
      "format": "uuid"
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "title": "Image URLs",
      "maxItems": 16,
      "minItems": 0
    },
    "moderation": {
      "enum": [
        "auto",
        "low"
      ],
      "type": "string",
      "default": "auto"
    },
    "resolution": {
      "enum": [
        "1k",
        "2k",
        "4k"
      ],
      "type": "string",
      "title": "Resolution",
      "default": "2k"
    },
    "aspect_ratio": {
      "enum": [
        "auto",
        "1:1",
        "3:2",
        "2:3",
        "4:3",
        "3:4",
        "16:9",
        "9:16",
        "21:9"
      ],
      "type": "string",
      "title": "Aspect Ratio",
      "default": "auto"
    },
    "enhance_prompt": {
      "type": "boolean",
      "title": "Enhance prompt",
      "default": false
    }
  },
  "additionalProperties": false
}
```

### Required Parameters Example

```json
{
  "prompt": "A cinematic scene at sunset",
  "quality": "high",
  "moderation": "auto",
  "resolution": "2k",
  "aspect_ratio": "auto",
  "enhance_prompt": false
}
```

### Output Schema

The shared polling endpoint returns one of the following status shapes:

```json
{
  "title": "RequestStatus",
  "oneOf": [
    {
      "title": "PendingRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "in_progress",
            "nsfw",
            "canceled"
          ]
        }
      },
      "required": [
        "status",
        "request_id"
      ]
    },
    {
      "title": "FailedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "failed"
        },
        "error": {
          "type": "string"
        }
      },
      "required": [
        "status",
        "request_id",
        "error"
      ]
    },
    {
      "title": "CompletedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "completed"
        },
        "images": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "url"
            ]
          }
        }
      },
      "required": [
        "status",
        "request_id",
        "images"
      ]
    }
  ]
}
```

## SDK Installation

Install one of the official server-side SDKs:

```bash
npm install @higgsfield/client
# or
pip install higgsfield-client
```

## Usage Examples

### TypeScript

```typescript
import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "marketing-studio/image/flare",
  {
    input: {
      "prompt": "A cinematic scene at sunset",
      "quality": "high",
      "moderation": "auto",
      "resolution": "2k",
      "aspect_ratio": "auto",
      "enhance_prompt": false
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'marketing-studio/image/flare',
    arguments={'prompt': 'A cinematic scene at sunset',
         'quality': 'high',
         'moderation': 'auto',
         'resolution': '2k',
         'aspect_ratio': 'auto',
         'enhance_prompt': False},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/marketing-studio/image/flare' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "A cinematic scene at sunset",
  "quality": "high",
  "moderation": "auto",
  "resolution": "2k",
  "aspect_ratio": "auto",
  "enhance_prompt": false
}
JSON
```

## Additional Documentation

# About

**Marketing Studio Image (2.5 Flare)** generates and edits campaign images. Set `enhance_prompt` to `true` to apply a Marketing Studio preset before rendering.

## 1. Direct generation or editing

Omit `image_urls` for generation. Pass one or more image URLs for editing (up to 16). Direct mode is the default.

```json
{
  "prompt": "A premium skincare campaign on sculptural stone",
  "resolution": "2k",
  "aspect_ratio": "3:2",
  "quality": "high",
  "enhance_prompt": false
}
```

## 2. Preset enhancement

Enhanced mode requires a preset and one product image. A second image is treated as the optional model reference. Without a second image, the composition stays product-only; the endpoint does not generate a person automatically.

### Get a preset UUID

Before sending an enhanced request, fetch the current visible presets with the same API credentials:

```http
GET https://api.higgsfield.ai/marketing-studio/image/presets?size=50
Authorization: Key KEY_ID:KEY_SECRET
```

The endpoint returns only visible, usable Ads presets. The response contains `{ "total": ..., "cursor": ..., "items": [...] }`. Let the user select a preset, then copy the selected item's `id` into the generation request as `preset_id`:

```json
{
  "items": [
    {
      "id": "7e68c81e-5f97-4f48-bcab-f0d4dd75a99d",
      "type": "ads",
      "name": "Premium Product Ad"
    }
  ]
}
```

Do not hardcode preset UUIDs or source them from a static enum: presets are managed in the CMS and can change visibility. If `cursor` is not `null`, pass it to the next catalog request to load another page. The preset catalog and `preset_id` are needed only when `enhance_prompt` is `true`.

### Send the enhanced request

```json
{
  "prompt": "Minimal, bright and premium",
  "image_urls": ["https://example.com/product.png"],
  "preset_id": "7e68c81e-5f97-4f48-bcab-f0d4dd75a99d",
  "resolution": "2k",
  "aspect_ratio": "auto",
  "quality": "high",
  "enhance_prompt": true
}
```

## 3. Request behavior

`resolution` supports `1k`, `2k`, and `4k`; the default is `2k`. `aspect_ratio` supports `auto`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, and `21:9`. In enhanced mode, `auto` uses the selected preset's aspect ratio.

`quality` supports `low`, `medium`, `high`, `xhigh`, and `max`; the default is `high`. Preset enhancement preserves the selected quality and renders with GPT Image 2.5 Flare.

Direct and enhanced requests use the same token rates, with no separate enhancement surcharge. The initial charge is an estimate reconciled against actual token usage on completion. Prompt length, reference images, resolution, and quality affect the final cost.

## 4. Authentication and queue

Send POST requests to `https://api.higgsfield.ai/marketing-studio/image/flare` with `Authorization: Key KEY_ID:KEY_SECRET`. The endpoint is asynchronous; poll the returned request ID or use a webhook.

## Additional Resources

- [Model page](https://console.higgsfield.ai/models/marketing-studio/image/flare)
- [This LLM-readable document](https://dash.higgsfield.ai/models/marketing-studio/image/flare/llms.txt)