--- title: "Image ad tools" description: "Generate image ads, clone ads, edit ad images and copy, and check generation status." url: "https://sellify.ai/docs/developers/mcp-tools/image-ads" --- # Image ad tools > Generate image ads, clone ads, edit ad images and copy, and check generation status. Generate image ads, clone ads, edit ad images and copy, and check generation status. This page lists 12 tools, 3 of them read-only. - [`ecom_winning_ad_list`](#ecom_winning_ad_list): List winning ads - [`ecom_image_ad_get_submission_status`](#ecom_image_ad_get_submission_status): Get image-ad generation status - [`ecom_image_ad_get_edit_status`](#ecom_image_ad_get_edit_status): Get image-edit status - [`ecom_image_ad_submit`](#ecom_image_ad_submit): Generate image ads for a product and sales angle - [`ecom_image_ad_clone`](#ecom_image_ad_clone): Clone a winning image ad for a product - [`ecom_image_ad_clone_from_saved_spy`](#ecom_image_ad_clone_from_saved_spy): Recreate a saved Ad Spy image for a product - [`ecom_image_ad_generate_more`](#ecom_image_ad_generate_more): Generate more variations from an image-ad submission - [`ecom_image_ad_update_meta_copy`](#ecom_image_ad_update_meta_copy): Edit an ad copy field - [`ecom_image_ad_request_image_edit`](#ecom_image_ad_request_image_edit): Request an AI image edit - [`ecom_image_ad_request_background_removal`](#ecom_image_ad_request_background_removal): Remove an ad image background - [`ecom_image_ad_set_current_version`](#ecom_image_ad_set_current_version): Select the current ad image version - [`ecom_image_ad_regenerate_copy`](#ecom_image_ad_regenerate_copy): Regenerate ad copy ## `ecom_winning_ad_list` **List winning ads** Lists the shared winning ads library, newest first. Filter by query (caption, brand, or source link) or adType. Each returned id is a winningAdId for cloning. | Property | Value | | -------------- | ---------------------- | | Access | Read-only | | Scope | Ads: read (`ads:read`) | | Credits | Free | | Safe to repeat | Yes | ### Input | Field | Type | Required | Description | | ----------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | No | Length up to 120. | | `adType` | enum | No | One of: `product_highlight`, `lifestyle`, `before_after`, `benefit_callout`, `announcement`, `promotion_discount`, `facts_statistics`, `faq_explainer`, `features_benefits`, `holiday_seasonal`, `humor_fun`, `native_ad`, `reasons_why`, `testimonial_reviews`, `ugc`, `unboxing`, `us_vs_them`. | | `limit` | integer | No | Between 1 and 100. Defaults to `25`. | | `cursor` | string or null | No | | | `response_format` | enum | No | "concise" (the default) shortens long text and leaves out nested details in each result. Pass "detailed" only when you need the full text or nested details of a result. One of: `concise`, `detailed`. Defaults to `"concise"`. | ### Output | Field | Type | Description | | ------------ | --------------- | ---------------- | | `winningAds` | array of object | Items up to 100. | | `nextCursor` | string or null | | | `hasMore` | boolean | | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_winning_ad_list", "arguments": {} } } ``` ## `ecom_image_ad_get_submission_status` **Get image-ad generation status** Returns progress, failure details, and safe visible results for one Ecom image-ad generation submission. | Property | Value | | -------------- | ---------------------- | | Access | Read-only | | Scope | Ads: read (`ads:read`) | | Credits | Free | | Safe to repeat | Yes | ### Input | Field | Type | Required | Description | | -------------- | ------------- | -------- | ----------- | | `submissionId` | string (uuid) | Yes | | ### Output | Field | Type | Description | | ----------------------------- | --------------------- | ------------------------------------------------------- | | `id` | string (uuid) | | | `status` | enum | One of: `pending`, `processing`, `completed`, `failed`. | | `error` | string or null | | | `parentSubmissionId` | string (uuid) or null | | | `requestedVariationCount` | integer or null | | | `imageGenerationFailureCount` | integer | | | `copyPending` | boolean | | | `copyFailureCount` | integer | | | `createdAt` | string | | | `startedAt` | string or null | | | `completedAt` | string or null | | | `updatedAt` | string | | | `result` | object or null | | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_get_submission_status", "arguments": { "submissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } ``` ## `ecom_image_ad_get_edit_status` **Get image-edit status** Returns the state and safe completed image URL for one asynchronous image edit. Internal storage paths are not exposed. | Property | Value | | -------------- | ---------------------- | | Access | Read-only | | Scope | Ads: read (`ads:read`) | | Credits | Free | | Safe to repeat | Yes | ### Input | Field | Type | Required | Description | | ----------- | ------------- | -------- | ----------- | | `versionId` | string (uuid) | Yes | | ### Output | Field | Type | Description | | -------------- | -------------------- | ------------------------------------------------------- | | `id` | string (uuid) | | | `submissionId` | string (uuid) | | | `status` | enum | One of: `pending`, `processing`, `completed`, `failed`. | | `error` | string or null | | | `url` | string (uri) or null | | | `mimeType` | string or null | | | `completedAt` | string or null | | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_get_edit_status", "arguments": { "versionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } ``` ## `ecom_image_ad_submit` **Generate image ads for a product and sales angle** Queues an ecom image ad generation and returns the submission id to poll. Charges image generation credits when the work completes. Build from a template with productId, one of its angleId values and an adType format, optionally with offerId, heroImageIds, aspectRatio and variationCount; to mix formats, set varyOptions.adFormat and list the formats in overrideAdTypes, primary first. Or build from a written brief with adType prompt\_led and userAdBrief, optionally with productId, and without formatId, varyOptions or overrideAdTypes. Use the template when the user names a saved product and sales angle, and look both up first. When they do not name an ad format, pass adType product\_highlight instead of asking which format to use. Use the written brief when the user describes the picture they want, passing productId too when they name a saved product. When the user gives you pictures to follow, such as a layout, a style or the product itself, pass them in reference\_images with the written brief. | Property | Value | | --------------- | --------------------------------------------------------- | | Access | Writes data | | Scope | Ads: write (`ads:write`) | | Credits | About 15 to 73 credits, depending on quantity and options | | Who can call it | Workspace owners and admins | ### Input | Field | Type | Required | Description | | ------------------ | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `productId` | string (uuid) | No | | | `angleId` | string (uuid) | No | | | `adType` | enum | Yes | One of: `prompt_led`, `product_highlight`, `lifestyle`, `before_after`, `benefit_callout`, `announcement`, `promotion_discount`, `facts_statistics`, `faq_explainer`, `features_benefits`, `holiday_seasonal`, `humor_fun`, `native_ad`, `reasons_why`, `testimonial_reviews`, `ugc`, `unboxing`, `us_vs_them`. | | `aspectRatio` | enum | No | One of: `1:1`, `4:5`, `16:9`, `9:16`. Defaults to `"1:1"`. | | `variationCount` | integer | No | Between 1 and 5. Defaults to `5`. | | `offerId` | string (uuid) | No | | | `formatId` | enum | No | One of: `announcement_promotion_discount`, `before_after`, `facts_statistics`, `faq_explainer`, `features_benefits`, `holiday_seasonal_discount`, `humor_funny`, `native_ad`, `reasons_to_buy`, `testimonials_reviews`, `ugc`, `unboxing`, `us_versus_them`, `bizarre_pattern_interrupt`. | | `varyOptions` | object | No | | | `overrideAdTypes` | array of enum | No | Items 1 to 17. | | `userAdBrief` | string | No | Length 1 to 3000. | | `heroImageIds` | array of string (uuid) | No | Items 1 to 10. | | `useBrandKit` | boolean | No | | | `reference_images` | array of object | No | Up to 5 pictures for the image model to follow, such as a layout, a style or the product itself. PNG, JPEG or WebP, up to 8 MB each. Only with adType prompt\_led and userAdBrief. Each item: Pass the file the user attached in ChatGPT, an upload\_id from create\_file\_upload, or a public https url. Items 1 to 5. | | `idempotency_key` | string | No | Client-chosen key identifying this write. Reuse it only when retrying the same call. Length 1 to 200. | | `max_credits` | number | Yes | The most credits this call may spend, with at most two decimals. Up to 10000. | ### Output | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------- | | `submissionId` | string (uuid) | | | `credits_charged` | number | Workspace credits charged by this call. | | `credits_left` | number or null | Workspace credits remaining after this call, or null when the balance could not be read. | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_submit", "arguments": { "adType": "prompt_led", "max_credits": 1 } } } ``` ## `ecom_image_ad_clone` **Clone a winning image ad for a product** Clones an ad from the shared winning ads library, identified by its winningAdId. Resolves or creates a closest-to-winner strategy, queues image generation, and returns the submission id to poll. | Property | Value | | --------------- | --------------------------------------------------------- | | Access | Writes data | | Scope | Ads: write (`ads:write`) | | Credits | About 73 to 80 credits, depending on quantity and options | | Who can call it | Workspace owners and admins | ### Input | Field | Type | Required | Description | | ----------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `winningAdId` | string (uuid) | Yes | | | `productId` | string (uuid) | Yes | | | `angleId` | string (uuid) | No | Optional. The clone angle made for this winning ad and product. Leave it out and Sellify finds or makes one. Ordinary sales angles are refused. | | `aspectRatio` | enum | No | One of: `1:1`, `4:5`, `16:9`, `9:16`. Defaults to `"1:1"`. | | `angleSummary` | string | No | Length 1 to 220. | | `formatSummary` | string | No | Length 1 to 220. | | `idempotency_key` | string | No | Client-chosen key identifying this write. Reuse it only when retrying the same call. Length 1 to 200. | | `max_credits` | number | Yes | The most credits this call may spend, with at most two decimals. Up to 10000. | ### Output | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------- | | `submissionId` | string (uuid) | | | `credits_charged` | number | Workspace credits charged by this call. | | `credits_left` | number or null | Workspace credits remaining after this call, or null when the balance could not be read. | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_clone", "arguments": { "winningAdId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "max_credits": 1 } } } ``` ## `ecom_image_ad_clone_from_saved_spy` **Recreate a saved Ad Spy image for a product** Prepares a durable clone strategy, queues image generation, and returns the submission id to poll. Pass angleId to write the ad on one of the product’s own sales angles instead; the clone analysis and its charge are then skipped. variationCount sets how many versions to generate, 1 to 5 (default 5), and the image charge is priced by it. | Property | Value | | --------------- | --------------------------------------------------------- | | Access | Writes data | | Scope | Ads: write (`ads:write`) | | Credits | About 15 to 80 credits, depending on quantity and options | | Who can call it | Workspace owners and admins | ### Input | Field | Type | Required | Description | | ----------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `savedSpyAdId` | string (uuid) | Yes | | | `productId` | string (uuid) | Yes | | | `angleId` | string (uuid) | No | Optional. One of the chosen product’s own sales angles. The ad is written on that angle and the clone analysis and its charge are skipped. Leave it out and Sellify analyses the saved ad and writes on the angle it finds. Clone angles and angles linked to another product are refused. | | `aspectRatio` | enum | No | One of: `1:1`, `4:5`, `16:9`, `9:16`. Defaults to `"1:1"`. | | `variationCount` | integer | No | How many versions of the ad to generate, 1 to 5. Defaults to 5. The image charge is priced by this count. Between 1 and 5. Defaults to `5`. | | `imageIndex` | integer | No | Between 0 and 49. | | `idempotency_key` | string | No | Client-chosen key identifying this write. Reuse it only when retrying the same call. Length 1 to 200. | | `max_credits` | number | Yes | The most credits this call may spend, with at most two decimals. Up to 10000. | ### Output | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------- | | `submissionId` | string (uuid) | | | `reused` | boolean | | | `credits_charged` | number | Workspace credits charged by this call. | | `credits_left` | number or null | Workspace credits remaining after this call, or null when the balance could not be read. | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_clone_from_saved_spy", "arguments": { "savedSpyAdId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "max_credits": 1 } } } ``` ## `ecom_image_ad_generate_more` **Generate more variations from an image-ad submission** Validates the parent and optional source variation, queues more image ads, and returns the submission id to poll. | Property | Value | | --------------- | ---------------------------------------------------------- | | Access | Writes data | | Scope | Ads: write (`ads:write`) | | Credits | About 15 to 145 credits, depending on quantity and options | | Who can call it | Workspace owners and admins | ### Input | Field | Type | Required | Description | | --------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `parentSubmissionId` | string (uuid) | Yes | | | `varyOptions` | object | No | Defaults to `\{\}`. | | `overrideAngleId` | string (uuid) | No | | | `overrideAdTypes` | array of enum | No | Items 1 to 17. | | `variationCount` | integer | No | Between 1 and 10. Defaults to `5`. | | `changeRequest` | string | No | Length up to 2000. | | `sourceAdRef` | object | No | | | `overrideAspectRatio` | enum | No | One of: `1:1`, `4:5`, `16:9`, `9:16`. | | `idempotency_key` | string | No | Client-chosen key identifying this write. Reuse it only when retrying the same call. Length 1 to 200. | | `max_credits` | number | Yes | The most credits this call may spend, with at most two decimals. Up to 10000. | ### Output | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------- | | `submissionId` | string (uuid) | | | `credits_charged` | number | Workspace credits charged by this call. | | `credits_left` | number or null | Workspace credits remaining after this call, or null when the balance could not be read. | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_generate_more", "arguments": { "parentSubmissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "max_credits": 1 } } } ``` ## `ecom_image_ad_update_meta_copy` **Edit an ad copy field** Updates one primary-text, headline, or description field on a visible generated ad and meters the persisted edit once. Look the ad up in the ad library first. Index 0 is the copy shown in its copyPreview. When copyPreview has primaryTextTruncated, the preview is only the start of the primary text, so replace it only with complete new text from the user and never write back an edited preview. Pass a new random UUID v4 as operationId for each edit, and reuse it only when retrying that same edit; a retry with the same operationId returns the first result without charging again, and reusing one for a different edit is refused. | Property | Value | | --------------- | --------------------------- | | Access | Changes or deletes data | | Scope | Ads: write (`ads:write`) | | Credits | About 0.2 credits | | Who can call it | Workspace owners and admins | | Safe to repeat | Yes | ### Input | Field | Type | Required | Description | | ------------- | ------------- | -------- | ----------------------------------------------------------------------------- | | `adRef` | object | Yes | | | `section` | enum | Yes | One of: `primaryTextVariations`, `headlines`, `descriptions`. | | `index` | integer | Yes | Between 0 and 4. | | `text` | string | Yes | Length 1 to 960. | | `operationId` | string (uuid) | Yes | | | `max_credits` | number | Yes | The most credits this call may spend, with at most two decimals. Up to 10000. | ### Output | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------- | | `submissionId` | string (uuid) | | | `variationId` | string | Length 1 to 100. | | `operationId` | string (uuid) | | | `credits_charged` | number | Workspace credits charged by this call. | | `credits_left` | number or null | Workspace credits remaining after this call, or null when the balance could not be read. | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_update_meta_copy", "arguments": { "adRef": { "submissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "variationId": "example" }, "section": "primaryTextVariations", "index": 1, "text": "example", "operationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "max_credits": 1 } } } ``` ## `ecom_image_ad_request_image_edit` **Request an AI image edit** Creates a version for a visible ad, queues an AI image edit, and returns the version id to poll. | Property | Value | | --------------- | --------------------------- | | Access | Writes data | | Scope | Ads: write (`ads:write`) | | Credits | About 14 credits | | Who can call it | Workspace owners and admins | ### Input | Field | Type | Required | Description | | ---------------------------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `adRef` | object | Yes | | | `prompt` | string | Yes | Length 1 to 2000. | | `sourceVersionId` | string (uuid) or null | No | | | `referenceImageStoragePaths` | array of string | No | Items up to 5. | | `aspectRatio` | enum | No | One of: `1:1`, `4:5`, `16:9`, `9:16`, `1.91:1`. | | `idempotency_key` | string | No | Client-chosen key identifying this write. Reuse it only when retrying the same call. Length 1 to 200. | | `max_credits` | number | Yes | The most credits this call may spend, with at most two decimals. Up to 10000. | ### Output | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------- | | `versionId` | string (uuid) | | | `versionNumber` | integer | | | `status` | "pending" | | | `credits_charged` | number | Workspace credits charged by this call. | | `credits_left` | number or null | Workspace credits remaining after this call, or null when the balance could not be read. | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_request_image_edit", "arguments": { "adRef": { "submissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "variationId": "example" }, "prompt": "example", "max_credits": 1 } } } ``` ## `ecom_image_ad_request_background_removal` **Remove an ad image background** Removes the background from a visible ad image, saves a completed version, and selects it as current. | Property | Value | | --------------- | --------------------------- | | Access | Writes data | | Scope | Ads: write (`ads:write`) | | Credits | About 0.05 credits | | Who can call it | Workspace owners and admins | ### Input | Field | Type | Required | Description | | ----------------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `adRef` | object | Yes | | | `sourceVersionId` | string (uuid) or null | No | | | `idempotency_key` | string | No | Client-chosen key identifying this write. Reuse it only when retrying the same call. Length 1 to 200. | | `max_credits` | number | Yes | The most credits this call may spend, with at most two decimals. Up to 10000. | ### Output | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------- | | `versionId` | string (uuid) | | | `versionNumber` | integer | | | `status` | "completed" | | | `credits_charged` | number | Workspace credits charged by this call. | | `credits_left` | number or null | Workspace credits remaining after this call, or null when the balance could not be read. | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_request_background_removal", "arguments": { "adRef": { "submissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "variationId": "example" }, "max_credits": 1 } } } ``` ## `ecom_image_ad_set_current_version` **Select the current ad image version** Selects a completed edit version for a visible ad, or selects the original image when versionId is null. | Property | Value | | --------------- | --------------------------- | | Access | Writes data | | Scope | Ads: write (`ads:write`) | | Credits | Free | | Who can call it | Workspace owners and admins | | Safe to repeat | Yes | ### Input | Field | Type | Required | Description | | ----------- | --------------------- | -------- | ----------- | | `adRef` | object | Yes | | | `versionId` | string (uuid) or null | Yes | | ### Output | Field | Type | Description | | ------------------ | --------------------- | ----------- | | `currentVersionId` | string (uuid) or null | | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_set_current_version", "arguments": { "adRef": { "submissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "variationId": "example" }, "versionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } ``` ## `ecom_image_ad_regenerate_copy` **Regenerate ad copy** Queues copy regeneration for all or selected visible variations of a completed generated image ad. Look the ad up in the ad library first, then pass its submissionId, and its variationId in variationIds. The new copy replaces the current headlines, primary text and descriptions, can replace lines the user edited, and cannot be undone. Set replaceEditedFields only when the user asks to replace their own edits too. The new copy is written in the background; list the ad again after a minute to read it. | Property | Value | | --------------- | --------------------------- | | Access | Changes or deletes data | | Scope | Ads: write (`ads:write`) | | Credits | About 0.3 credits | | Who can call it | Workspace owners and admins | ### Input | Field | Type | Required | Description | | --------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `submissionId` | string (uuid) | Yes | | | `variationIds` | array of string | Yes | Items up to 100. | | `replaceEditedFields` | boolean | No | Defaults to `false`. | | `idempotency_key` | string | No | Client-chosen key identifying this write. Reuse it only when retrying the same call. Length 1 to 200. | | `max_credits` | number | Yes | The most credits this call may spend, with at most two decimals. Up to 10000. | ### Output | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------- | | `submissionId` | string (uuid) | | | `status` | enum | One of: `queued`, `already_pending`. | | `credits_charged` | number | Workspace credits charged by this call. | | `credits_left` | number or null | Workspace credits remaining after this call, or null when the balance could not be read. | ### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ecom_image_ad_regenerate_copy", "arguments": { "submissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "variationIds": [ "example" ], "max_credits": 1 } } } ``` ## Related [Tool reference overview](https://sellify.ai/docs/developers/mcp-tools) · [Authentication](https://sellify.ai/docs/developers/authentication) · [Credits and limits](https://sellify.ai/docs/developers/credits-and-limits)