# Ads Studio

> From a simple brief to ready-to-use ads. Bring your product, describe your vision, and let Ads Studio handle the creative.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/higgsfield/ads-studio/v1.0`
- **Model ID**: `higgsfield/ads-studio/v1.0`
- **Category**: text2image
- **Kind**: inference

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

- **`niche`** (`string`, _optional_):
  - Default: `""`

- **`prompt`** (`string`, _required_):

- **`language`** (`string`, _optional_):
  - Default: `""`

- **`batch_size`** (`integer`, _optional_):
  - Default: `1`

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

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

- **`target_audience`** (`string`, _optional_):
  - Default: `""`

### Input JSON Schema

```json
{
  "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"
      ],
      "type": "string",
      "default": "1:1"
    },
    "target_audience": {
      "type": "string",
      "default": "",
      "maxLength": 2000
    }
  },
  "additionalProperties": false
}
```

### Required Parameters Example

```json
{
  "niche": "",
  "prompt": "A cinematic scene at sunset",
  "language": "",
  "batch_size": 1,
  "image_urls": [],
  "aspect_ratio": "1:1",
  "target_audience": ""
}
```

### 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(
  "higgsfield/ads-studio/v1.0",
  {
    input: {
      "niche": "",
      "prompt": "A cinematic scene at sunset",
      "language": "",
      "batch_size": 1,
      "image_urls": [],
      "aspect_ratio": "1:1",
      "target_audience": ""
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'higgsfield/ads-studio/v1.0',
    arguments={'niche': '',
         'prompt': 'A cinematic scene at sunset',
         'language': '',
         'batch_size': 1,
         'image_urls': [],
         'aspect_ratio': '1:1',
         'target_audience': ''},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/higgsfield/ads-studio/v1.0' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "niche": "",
  "prompt": "A cinematic scene at sunset",
  "language": "",
  "batch_size": 1,
  "image_urls": [],
  "aspect_ratio": "1:1",
  "target_audience": ""
}
JSON
```

## Additional Resources

- [Model page](https://console.higgsfield.ai/models/higgsfield/ads-studio/v1.0)
- [This LLM-readable document](https://dash.higgsfield.ai/models/higgsfield/ads-studio/v1.0/llms.txt)