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

# generate_ad_image

> Generate ad images for a product with Copyfy's AI image creator.

Generates ad images with Copyfy's AI image creator, the same generation as **Creatives AI** in the dashboard, and saves them to your Copyfy library. Pass a product to show it in the ad: its main image becomes the product reference. Pass an image ad from [`search_ads`](https://docs.copyfy.io/tools/search-ads) to follow its layout and style, like **Copy ad** in the dashboard.

Copyfy tells your assistant to state the cost and wait for your go-ahead before calling it, and marks it as a tool that spends credits, so your client can ask you first.

**Cost:** 1 MCP credit, given back if the generation fails, plus AI credits: 1 per image, 2 per image with `recraft/recraft-v4-pro`, `recraft/recraft-v4`, or `google/gemini-3-pro-image`. Image generation spends your legacy image credits first, then your AI credits, as in the dashboard. If the generation fails without an image, the AI credits are refunded. A generation that times out keeps them, as in the dashboard.

## Arguments

| Argument | Type | Allowed values |
| - | - | - |
| `prompt` | string | Required, 3 to 2,000 characters. What the ad shows: scene, how the product appears, mood, text to print on the image, layout. |
| `product_id` | integer or numeric string | Copyfy product id, from [`search_products`](https://docs.copyfy.io/tools/search-products) or [`get_product`](https://docs.copyfy.io/tools/get-product). |
| `style_reference_ad_id` | integer or numeric string | Id of an image ad from [`search_ads`](https://docs.copyfy.io/tools/search-ads). Video and carousel ads are refused. |
| `image_count` | integer | 1 to 4, default 1. |
| `aspect_ratio` | string | `auto`, `1:1` (default), `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `4:5`, `5:4`. |
| `model` | string | `google/gemini-3.1-flash-image` (default), `openai/gpt-image-2.5-flare`, `google/gemini-3-pro-image`, `openai/gpt-image-2.5-sunburst`, `bytedance/seedream-5.0-lite`, `bfl/flux-kontext-max`, `recraft/recraft-v4-pro`, `recraft/recraft-v4`. `bytedance/seedream-5.0-lite` and the Recraft models cannot use `product_id` or `style_reference_ad_id`. |
| `max_ai_credits` | number | The most AI credits you accept to spend. A call that would cost more is refused and nothing is charged. |

## Example

```json Tool call theme={null}
{
  "name": "generate_ad_image",
  "arguments": {
    "prompt": "The brush on a bathroom shelf, soft morning light, headline: No more hair on the couch",
    "product_id": 4419021,
    "aspect_ratio": "4:5",
    "image_count": 2,
    "max_ai_credits": 2
  }
}
```

```json Result theme={null}
{
  "job": { "id": "img_mcp-6f1c2a9e0b7d4c3a8e5f1b2c3d4e5f60", "kind": "ad_image", "status": "running", "poll_after_seconds": 10 },
  "ai_credits": { "charged": 2, "remaining": 148.5 },
  "mcp_credits_charged": 1,
  "image_count": 2,
  "model": "google/gemini-3.1-flash-image",
  "product": { "id": 4419021, "title": "Self-Cleaning Pet Brush" },
  "dashboard_url": "https://app.copyfy.io/dashboard/creatives-ai",
  "library_url": "https://app.copyfy.io/library",
  "message": "Copyfy is generating the images. Call get_job_status with job.id after poll_after_seconds; they are also saved to the user's Copyfy library."
}
```

Images usually take 15 to 90 seconds. Follow the job with [`get_job_status`](https://docs.copyfy.io/tools/get-job-status): when it succeeds, `images` lists each `image_url`.

## Result fields

| Field | Type | Description |
| - | - | - |
| `job` | object | `id`, `kind` (`ad_image`), `status` (`running`), and `poll_after_seconds`. |
| `ai_credits` | object | `charged`: AI credits reserved for this generation. `remaining`: your balance after it, image credits included. |
| `mcp_credits_charged` | integer | 1. |
| `product`, `style_reference_ad_id` | object, integer | The references used, when you passed them. |
| `dashboard_url`, `library_url` | string | Creatives AI and your library, where the images also appear. |

## Errors

| Code | When |
| - | - |
| [`insufficient_credits`](https://docs.copyfy.io/errors#insufficient_credits) | Not enough AI credits. Nothing is charged. The error includes `required_credits`, `remaining_credits`, and `buy_credits_url`. |
| [`cost_limit_exceeded`](https://docs.copyfy.io/errors#cost_limit_exceeded) | The generation costs more than `max_ai_credits`. Nothing is charged. |
| [`paid_plan_required`](https://docs.copyfy.io/errors#paid_plan_required) | The account is in a trial. |
| [`invalid_arguments`](https://docs.copyfy.io/errors#invalid_arguments) | The model cannot use the references you passed, or the ad is a video or a carousel. |
| [`not_found`](https://docs.copyfy.io/errors#not_found) | No Copyfy product or ad has this id. |
| [`media_unavailable`](https://docs.copyfy.io/errors#media_unavailable) | Copyfy could not download the product or ad image. |
| [`service_unavailable`](https://docs.copyfy.io/errors#service_unavailable) | The generation could not start. When the error includes `job_id`, Copyfy could not confirm whether it started, and the MCP credit stays set aside until the job settles it: check that job with [`get_job_status`](https://docs.copyfy.io/tools/get-job-status) before trying again. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.