Ads Studio — Generate ads API - Higgsfield API Docs

← Ads Studio Endpoint: POST https://api.higgsfield.ai/higgsfield/ads-studio/v1.0 Endpoint ID: higgsfield/ads-studio/v1.0 ▶Open API PlaygroundAds Studio · Generate ads↗

Usage notes

Submit one request with your brief. Ad concepts are prepared automatically, then rendered as images; no separate preparation or generate call is required.
batch_size selects 1–8 ad concepts. Each concept produces one image, so a fully successful batch returns batch_size images.
Rendering uses GPT Image 2.5 Flare with fixed 2k resolution and high quality. Exact dimensions depend on aspect_ratio. quality, resolution, renderer and fallback model are not public inputs.
All outputs in a batch use the requested aspect_ratio. Omitting it selects 1:1. The value auto is not supported.
Set HF_API_KEY_ID and HF_API_KEY_SECRET to your API credentials. Set a unique IDEMPOTENCY_KEY for each intended generation; reuse it only when retrying that same request.

Quick start

curl --request POST \
  --url https://api.higgsfield.ai/higgsfield/ads-studio/v1.0 \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
  "prompt": "Create two distinct ads for a fictional herbal tea called Quiet Evening. Use a green tea tin, warm light and the headline Make time for yourself. No people.",
  "target_audience": "Busy professionals looking for a relaxing evening ritual",
  "niche": "Herbal tea",
  "language": "en",
  "aspect_ratio": "9:16",
  "batch_size": 2
}'

import higgsfield_client

arguments = (
    {'prompt': 'Create two distinct ads for a fictional herbal tea called Quiet '
               'Evening. Use a green tea tin, warm light and the headline Make '
               'time for yourself. No people.',
     'target_audience': 'Busy professionals looking for a relaxing evening ritual',
     'niche': 'Herbal tea',
     'language': 'en',
     'aspect_ratio': '9:16',
     'batch_size': 2}
)
result = higgsfield_client.subscribe(
    "higgsfield/ads-studio/v1.0",
    arguments=arguments,
)
print(result["images"][0]["url"])

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

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

const result = await higgsfield.subscribe("higgsfield/ads-studio/v1.0", {
  input:
    {
      "prompt": "Create two distinct ads for a fictional herbal tea called Quiet Evening. Use a green tea tin, warm light and the headline Make time for yourself. No people.",
      "target_audience": "Busy professionals looking for a relaxing evening ritual",
      "niche": "Herbal tea",
      "language": "en",
      "aspect_ratio": "9:16",
      "batch_size": 2
    },
  withPolling: true,
});

if (result.status === "completed") {
  console.log(result.images?.[0]?.url);
}

Input schema

string

default:""

Optional product category or business niche used to guide ad concepts. Maximum characters: 1000.

string

required

Required marketing brief describing the product or service, desired message and visual direction. Must contain non-whitespace text. Minimum characters: 1. Maximum characters: 8000. Pattern: \S.

string

default:""

Optional language guidance for ad copy, for example en or ru. This is free text, not a fixed language-code enum. Maximum characters: 80.

integer

default:"1"

Number of ad concepts and requested output images. Billing is summed across the rendered images. Minimum: 1. Maximum: 8.

array

default:"[]"

Optional product or visual reference images. Supply up to 10 directly downloadable HTTP(S) URLs. Omit or send [] for text-only generation. Maximum items: 10. Each item: string. Minimum characters: 1. Maximum characters: 8192. Pattern: ^https?://.

string

default:"1:1"

Output width-to-height ratio shared by every image in the batch. Allowed values: "1:1", "4:5", "5:4", "16:9", "9:16", "4:3", "3:4", "21:9", "3:2", "2:3", "2:1", "1:2", "3:1", "1:3".

string

default:""

Optional description of the intended audience, such as interests, needs or use cases. Maximum characters: 2000.

Complete JSON schema

{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "niche": {
      "type": "string",
      "default": "",
      "maxLength": 1000
    },
    "prompt": {
      "type": "string",
      "pattern": "\\S",
      "maxLength": 8000,
      "minLength": 1
    },
    "language": {
      "type": "string",
      "default": "",
      "maxLength": 80
    },
    "batch_size": {
      "type": "integer",
      "default": 1,
      "maximum": 8,
      "minimum": 1
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^https?://",
        "maxLength": 8192,
        "minLength": 1
      },
      "default": [],
      "maxItems": 10
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "4:5",
        "5:4",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "21:9",
        "3:2",
        "2:3",
        "2:1",
        "1:2",
        "3:1",
        "1:3"
      ],
      "type": "string",
      "default": "1:1"
    },
    "target_audience": {
      "type": "string",
      "default": "",
      "maxLength": 2000
    }
  },
  "additionalProperties": false
}

Product references

Omit image_urls for text-only generation. To guide the ad with your product, send direct image URLs that the service can download without browser cookies or custom authentication headers. An unexpired signed HTTPS URL is suitable. Keep the URLs valid while the request is being processed.

{
  "prompt": "Create three distinct premium perfume ads. Preserve the bottle and label. Use the headline Leave a lasting note.",
  "image_urls": ["https://example.com/product.png"],
  "target_audience": "People looking for a distinctive gift",
  "niche": "Fragrance",
  "language": "en",
  "aspect_ratio": "4:5",
  "batch_size": 3
}

Reference images guide generation; exact preservation of a product, label or text is not guaranteed. Supported oversized references are normalized before rendering. The output remains a PNG at the selected aspect ratio.

Pricing

Illustrative estimate: approximately $0.084 per image. This is a budgeting example, not a fixed charge or maximum price. Actual cost varies with the aspect ratio, prepared prompt, reference images and measured token usage. Consult the current model pricing in the Playground before submitting work.

Token category	USD per 1 million tokens
Text input	$5.00
Cached text input	$1.25
Text output	$10.00
Image input	$8.00
Cached image input	$2.00
Image output	$30.00

The initial charge is an estimate reconciled to actual rendering usage on completion, with standard credit rounding. Cached input is charged at the cached rate instead of being counted again as uncached input. Ad concept preparation is not billed separately. For a batch, the final price is the sum of the actual image charges. Do not multiply aggregated batch token usage by batch_size again. Three images at the illustrative estimate would budget approximately $0.252; the actual total can differ.

Check request status

Use the returned status_url with the same API credentials. Set REQUEST_ID to the identifier returned when you submit the request:

curl --request GET \
  --url "https://api.higgsfield.ai/requests/${REQUEST_ID}/status" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"

Follow the shared polling guidance. A request handle confirms acceptance, not successful image generation. Stop polling on completed, failed, nsfw, or canceled, and inspect the returned outputs and errors.

Response

Submission returns one request handle for the entire batch:

Accepted

{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}

A fully successful two-image batch returns two indexed images:

Completed

{
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel",
  "status": "completed",
  "images": [
    {"index": 0, "url": "https://example.com/ad-1.png"},
    {"index": 1, "url": "https://example.com/ad-2.png"}
  ],
  "errors": []
}

Process every returned image rather than only images[0]. Use its zero-based index to identify its batch slot and inspect errors for unsuccessful slots. After subscribe returns, extend the Python quick start with:

for image in result.get("images", []):
    print(image["index"], image["url"])
for error in result.get("errors", []):
    print(error)

See idempotent requests, polling, request errors and authentication for shared request handling.

Get started

Model API reference

Core concepts

SDKs

Organizations

API reference

Resources

Ads Studio — Generate ads API

Usage notes

Quick start

Input schema

Product references

Pricing

Check request status

Response

​Usage notes

​Quick start

​Input schema

​Product references

​Pricing

​Check request status

​Response

Usage notes

Quick start

Input schema

Product references

Pricing

Check request status

Response