# Marketing Studio Image

> Creates and edits campaign images up to 4K from text or images.

## Overview

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

## Pricing

Public pricing information is not available for this model.

## 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`

- **`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": {
          "quality": {
            "const": "high"
          },
          "image_urls": {
            "maxItems": 2,
            "minItems": 1
          }
        }
      }
    }
  ],
  "title": "Marketing Studio Image",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "title": "Prompt",
      "maxLength": 5000,
      "minLength": 1,
      "description": "Write your prompt here"
    },
    "quality": {
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "type": "string",
      "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",
  {
    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',
    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' \
  --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** 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. Direct mode is the default.

```json
{
  "prompt": "A premium skincare campaign on sculptural stone",
  "resolution": "2k",
  "aspect_ratio": "3:2",
  "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",
  "enhance_prompt": true
}
```

## 3. Request behavior

`resolution` supports `1k`, `2k`, and `4k`. `aspect_ratio` supports `auto`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, and `21:9`. Enhanced requests cost 10% more than the equivalent direct request.

## 4. Authentication and queue

Send requests to `https://api.higgsfield.ai/marketing-studio/image` 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)
- [This LLM-readable document](https://dash.higgsfield.ai/models/marketing-studio/image/llms.txt)