> ## Documentation Index
> Fetch the complete documentation index at: https://docs.higgsfield.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketing Studio Image Generate and Edit API

> Generate or edit campaign images with Marketing Studio Image.

<div className="models-color-scope" aria-hidden="true" />

<div className="model-workflow-tabs" aria-label="Marketing Studio Image endpoints">
  <a className="model-workflow-tab is-active" href="/docs/models/marketing-studio-image/generate-and-edit">Generate and edit</a>
</div>

**Endpoint:** `POST https://api.higgsfield.ai/marketing-studio/image`

**Endpoint ID:** `marketing-studio/image`

<a className="model-playground-card" href="https://console.higgsfield.ai/models/marketing-studio%2Fimage/playground" target="_blank" rel="noreferrer">
  <span className="model-playground-icon">▶</span>
  <span className="model-playground-copy"><span className="model-playground-title">Try Marketing Studio Image</span><span>Open this endpoint in the Higgsfield API Playground.</span></span>
  <span className="model-card-arrow">↗</span>
</a>

## Quick Start

<CodeGroup>
  ```python Python theme={"dark"}
  import higgsfield_client

  result = higgsfield_client.subscribe(
      "marketing-studio/image",
      arguments={
          "prompt": "A clean summer launch campaign for a citrus sparkling drink",
          "resolution": "2k",
          "aspect_ratio": "4:3",
          "quality": "high",
      },
  )

  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"dark"}
  import { config, higgsfield } from "@higgsfield/client/v2";

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

  const result = await higgsfield.subscribe(
    "marketing-studio/image",
    {
      input: {
        prompt: "A clean summer launch campaign for a citrus sparkling drink",
        resolution: "2k",
        aspect_ratio: "4:3",
        quality: "high",
      },
      withPolling: true,
    },
  );

  if (result.isCompleted) console.log(result.jobs[0].results?.raw.url);
  ```

  ```bash cURL theme={"dark"}
  curl --request POST \
    --url https://api.higgsfield.ai/marketing-studio/image \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --data '{
      "prompt": "A clean summer launch campaign for a citrus sparkling drink",
      "resolution": "2k",
      "aspect_ratio": "4:3",
      "quality": "high"
    }'
  ```
</CodeGroup>

## Input Schema

<ParamField body="prompt" type="string" required>
  Campaign instructions from 1 to 5,000 characters.
</ParamField>

<ParamField body="image_urls" type="array">
  Publicly accessible reference image URLs. Direct mode accepts up to 16. Enhanced mode requires one product image and accepts one optional model image, in that order.
</ParamField>

<ParamField body="resolution" type="string" default="2k">
  Output resolution. Supported values: `1k`, `2k`, `4k`.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Supported values: `auto`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`. If omitted, direct mode uses a square output. In enhanced mode, `auto` or an omitted value uses the selected preset's aspect ratio.
</ParamField>

<ParamField body="quality" type="string" default="high">
  Supported values: `low`, `medium`, `high`. Enhanced mode always renders at `high` quality.
</ParamField>

<ParamField body="moderation" type="string" default="auto">
  Supported values: `auto`, `low`.
</ParamField>

<ParamField body="enhance_prompt" type="boolean" default="false">
  Build a preset-guided campaign composition. When `true`, `preset_id` and at least one `image_urls` item are required.
</ParamField>

<ParamField body="preset_id" type="string">
  UUID returned by the [Marketing Studio presets endpoint](#list-marketing-studio-presets). Required when `enhance_prompt` is `true`.
</ParamField>

## List Marketing Studio presets

`GET https://api.higgsfield.ai/marketing-studio/image/presets`

Use this endpoint to retrieve valid `preset_id` values for enhanced requests.

| Query parameter | Type    | Default | Description                                             |
| --------------- | ------- | ------- | ------------------------------------------------------- |
| `search`        | string  | —       | Search preset or group names. Accepts 1–100 characters. |
| `size`          | integer | `50`    | Results per page. Accepts 1–100.                        |
| `cursor`        | integer | `0`     | Zero-based pagination cursor.                           |

```bash theme={"dark"}
curl --request GET \
  --url "https://api.higgsfield.ai/marketing-studio/image/presets?size=50&cursor=0"
```

```json theme={"dark"}
{
  "total": 120,
  "cursor": 50,
  "items": [
    {
      "id": "<preset-uuid>",
      "type": "ads",
      "name": "Editorial product portrait",
      "cover_image": null,
      "metadata": {
        "aspect_ratio": "3:4",
        "group_name": "Editorial"
      },
      "format_slugs": []
    }
  ]
}
```

The response `cursor` is `null` when there are no more results.

## Output Schema

<ResponseField name="status" type="string" required>
  Request state. A newly accepted request returns `queued`.
</ResponseField>

<ResponseField name="request_id" type="string" required>
  Stable identifier used for polling, cancellation, and support.
</ResponseField>

<ResponseField name="status_url" type="string" required>
  URL to poll until the request reaches a terminal state.
</ResponseField>

<ResponseField name="cancel_url" type="string" required>
  URL used to cancel a request before processing starts.
</ResponseField>

<ResponseField name="images" type="array">
  Completed image outputs. Each item contains a download `url`.
</ResponseField>

## Input Examples

Replace `<preset-uuid>` with an `id` returned by [List Marketing Studio presets](#list-marketing-studio-presets) before submitting the preset-guided example.

<CodeGroup>
  ```json Direct generation theme={"dark"}
  {
    "prompt": "A clean summer launch campaign for a citrus sparkling drink",
    "resolution": "2k",
    "aspect_ratio": "4:3",
    "quality": "high"
  }
  ```

  ```json Direct edit theme={"dark"}
  {
    "prompt": "Place the product in a bright poolside campaign scene",
    "image_urls": ["https://cdn.example.com/product.png"],
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "quality": "high"
  }
  ```

  ```json Preset-guided theme={"dark"}
  {
    "prompt": "Premium, minimal, warm morning light",
    "image_urls": [
      "https://cdn.example.com/product.png",
      "https://cdn.example.com/model.png"
    ],
    "preset_id": "<preset-uuid>",
    "enhance_prompt": true,
    "resolution": "2k",
    "aspect_ratio": "auto"
  }
  ```
</CodeGroup>

## Output Example

<CodeGroup>
  ```json Accepted theme={"dark"}
  {
    "status": "queued",
    "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
    "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
    "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
  }
  ```

  ```json Completed theme={"dark"}
  {
    "status": "completed",
    "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
    "images": [{ "url": "https://cdn.example.com/marketing-studio-image.png" }]
  }
  ```
</CodeGroup>

<Tip>
  Use an SDK for automatic polling, or poll the returned [status URL](/docs/concepts/polling).
</Tip>


## Related topics

- [Marketing Studio Image API](/docs/models/marketing-studio-image.md)
- [Grok Image 2.0 Generate and Edit API](/docs/models/grok-image-2/generate-and-edit.md)
- [Image Generation API](/docs/models/image-generation.md)
- [Model API Reference](/docs/models.md)
- [SOUL 2 API](/docs/models/soul-2.md)