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

# OpenAI Setup

> Connect OpenAI to MagicAds — it powers the Image Studio (GPT Image 2) and Copy Studio (GPT-5.x), and can act as an alternate image engine in the Fashion Studio and Product Photoshoot plugins.

## Introduction

OpenAI is one of the broadest providers on the platform. A single key drives:

* the **Image Studio** via GPT Image 2,
* the **Copy Studio** via the GPT-5.x text models, and
* an optional alternate image engine inside the **Fashion Studio** and **Product Photoshoot** plugins.

This guide walks you through getting an OpenAI key, adding it in MagicAds, and the full list of models it unlocks.

## How keys are stored

All AI provider keys live in the **AI Settings** screen and are stored **encrypted** in the database. There are no `.env` edits and no code changes — keys are injected into the drivers at runtime. Users never supply their own key; every generation runs on the admin's key.

<Note>
  A model only becomes available to users when **both** are true: the provider's API key is saved **and** the model is **enabled** in the vendor modal.
</Note>

## Before you start

* Admin access to your MagicAds platform.
* An OpenAI account with a funded billing balance.
* Access to the required models (notably `gpt-image-2`) on your OpenAI account.

## Part 1 — Get your OpenAI API key

<Steps>
  <Step title="Sign in to the OpenAI platform">
    Go to [platform.openai.com](https://platform.openai.com/) and sign in (or create an account). The **API platform** is separate from ChatGPT — make sure you're on `platform.openai.com`, not `chatgpt.com`.
  </Step>

  <Step title="Set up billing first">
    Open **Settings → Billing** and add a payment method. OpenAI's API runs on **prepaid credits** or invoiced usage — add a small starting balance so your key can make calls. OpenAI charges you directly for usage; this is separate from your MagicAds platform credits.
  </Step>

  <Step title="Open the API keys page">
    Go to **Dashboard → API keys** (direct link: [platform.openai.com/api-keys](https://platform.openai.com/api-keys)). If your account uses **projects**, pick the project the key should belong to first.
  </Step>

  <Step title="Create a secret key">
    Click **Create new secret key**, give it a name (e.g. "MagicAds"), optionally scope it to a project, and (if asked for permissions) choose **All**. Click **Create**.

    <Warning>
      The secret key is shown **only once**. Copy it immediately and store it somewhere safe — you can't view it again later, only regenerate it.
    </Warning>
  </Step>

  <Step title="Confirm model access">
    Make sure your account can use the image model `gpt-image-2` and the GPT-5.x chat models. Some models require a minimum spend tier or organization verification on your OpenAI account.
  </Step>
</Steps>

## Part 2 — Add the key in MagicAds

<Steps>
  <Step title="Open AI Settings">
    In your platform, go to **Admin → AI Settings**.
  </Step>

  <Step title="Open the OpenAI vendor">
    Click the **OpenAI** vendor card to open its configuration modal.
  </Step>

  <Step title="Paste the key">
    Paste your secret key into the **API key** field. Leaving it blank keeps the existing key unchanged.
  </Step>

  <Step title="Enable the models you want">
    Toggle on the OpenAI models you want to offer and set each model's **credit cost** (what a user is charged per generation). For GPT Image 2 you can also set the **image quality** (see below).
  </Step>

  <Step title="Save">
    Click **Save**. The OpenAI card now shows as connected, and the enabled models appear in the relevant studios.
  </Step>
</Steps>

<Note>
  There is no "test connection" button. To verify, enable a model and run a quick generation in the matching studio.
</Note>

## Part 3 — Supported OpenAI models

### Image Studio

| Model              | Model ID      | Default credits | Notes                                                                                                                                                                 |
| ------------------ | ------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OpenAI GPT Image 2 | `gpt-image-2` | 2               | Quality-first image engine. Best-in-class **English text rendering**, high-fidelity edits, up to 4K. Supports reference-image input and an adjustable render quality. |

**Image quality knob (GPT Image 2 only):** in the vendor modal you can pick `auto`, `low`, `medium`, or `high`. Quality is the biggest lever on speed — `high` is slowest, `medium` is the recommended balance.

### Copy Studio

| Model        | Model ID       | Tier     | Default credits | Best for                                                 |
| ------------ | -------------- | -------- | --------------- | -------------------------------------------------------- |
| GPT-5.5      | `gpt-5.5`      | Premium  | 3               | Flagship quality for complex, high-converting ad copy.   |
| GPT-5.4      | `gpt-5.4`      | Premium  | 2               | More affordable flagship-tier; excellent all-round copy. |
| GPT-5.4 Mini | `gpt-5.4-mini` | Standard | 1               | Fast and cost-efficient; great for high-volume runs.     |
| GPT-5.4 Nano | `gpt-5.4-nano` | Fast     | 1               | Smallest/cheapest; ideal for short copy.                 |

### Also used by plugins

The **Fashion Studio** and **Product Photoshoot** plugins can use OpenAI's `gpt-image-2` as their image engine (selected on each plugin's own settings page). They read the same OpenAI key, so once it's configured here those plugins can use it too.

<Note>
  Credit costs shown are the seeded defaults. You can change any model's credit cost in the vendor modal. These are what your platform charges users in credits — they are not OpenAI's prices.
</Note>

## Part 4 — Make OpenAI a default (optional)

In the global section of **AI Settings** you can set the **default copy engine** to OpenAI and the **default image model** to OpenAI GPT Image 2, so they're pre-selected for users. You can also toggle each studio (Image / Video / Copy) on or off and control free-tier access there.

## Troubleshooting

| Symptom                                | Likely cause                                                    | Fix                                                                                 |
| -------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| OpenAI models don't appear to users    | Key missing or models disabled                                  | Add the key in the OpenAI vendor modal and enable the models, then Save.            |
| "The payload is invalid." on generate  | Saved key can't be decrypted (e.g. after an environment change) | Re-enter the OpenAI key in AI Settings and Save to refresh it.                      |
| Image generations are slow             | GPT Image 2 quality set to `high`                               | Lower it to `medium` in the vendor modal.                                           |
| OpenAI API errors / 401                | Invalid key or no model access/billing                          | Re-check the key, billing balance, and `gpt-image-2` access in your OpenAI account. |
| Copy generation fails only for GPT-5.5 | Account lacks access to that model                              | Disable that model or enable a tier your account can use.                           |

<Note>
  Keys are stored encrypted and applied at runtime. No `.env` changes or commands are needed after saving.
</Note>