# Create quote AI design (`create_quote_ai_design`)

Convert one file of a quote of this store with the AI sign designer, as Convert with AI does in the merchant admin. Name the file with the field_id and file_index of the quote files, from get_quote. The file is sent to the external AI image providers that the AI sign designer uses. One credit is held now, charged when the design is delivered, and released if it is refused or fails. A file is converted once: a file converted before returns that design and holds no credit. The design runs in the background: read it with get_ai_design. Requires ai_sign_designs:write and quotes:read. An actual conversion needs confirm: true, max_credits: 1 and an idempotency_key that is bound to the exact quote file. Supports dry_run, which holds no credit and starts nothing.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/create_quote_ai_design/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/create_quote_ai_design.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `ai_sign_designs:write`
- Behaviour: destructive write

## Purpose

Turn a logo or artwork file a shopper sent with a quote into a sign design.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | false |
| destructiveHint | true |
| idempotentHint | true |
| openWorldHint | true |

## Prerequisites

- A quote id from list_quotes, and the field_id and file_index of one of its files from get_quote.
- A merchant has connected this store and approved the ai_sign_designs:write and quotes:read scopes.
- The merchant agrees to spend one credit. Call get_ai_sign_design_capabilities to see the available credits.

## Side effects

- Holds one credit of the store. Delivery charges it; a refused or failed design releases it.
- Sends the quote file to the external AI image providers that the AI sign designer uses.
- Copies the quote file to private storage. The quote does not change.
- Claims the idempotency_key for at least 24 hours.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `quote_id` | integer | yes | The quote id, from list_quotes. |
| `field_id` | string | yes | The field_id of the quote file, from get_quote files. |
| `file_index` | integer | yes | The file_index of the quote file, from get_quote files. |
| `max_credits` | integer | unless `dry_run` is true | The most credits this conversion can spend, which must be 1: a delivered design uses one credit and a refused or failed design uses none. |
| `confirm` | boolean | unless `dry_run` is true | Must be true to apply the change, because the conversion holds one credit of the store and sends the quote file to external AI image providers. Without it the call returns a confirmation_required error and changes nothing. |
| `idempotency_key` | string | unless `dry_run` is true | A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict. |
| `dry_run` | boolean | no | When true, the conversion is checked against the quote, its file, the capacity and the available credits is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false. A dry run claims no key. A dry run does not require the confirm argument. |

## Result

The new design in processing state. Read it again with get_ai_design until status is delivered, refused or failed. A file converted before returns that design and holds nothing. A dry run returns ai_design_id (the design already made from the file, or null), the credits the conversion would hold and the credits available, and holds nothing.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `ai_design` | object | no | The design of the quote file. Absent on a dry run. |
| `ai_design.id` | integer | yes |  |
| `ai_design.origin` | string | yes | customer_customiser (a shopper used the AI sign designer), quote (a quote file was converted), merchant_admin (an upload in the merchant admin) or api (an AI sign design job). Expected to grow. One of: `customer_customiser`, `quote`, `merchant_admin`, `api`. |
| `ai_design.status` | string | yes | processing, then delivered (a design exists), refused (a check refused the design) or failed (no design for another reason). No credit is charged for refused or failed. Expected to grow. One of: `processing`, `delivered`, `refused`, `failed`. |
| `ai_design.product_family` | string or null | no | One of: `neon`, `channel_letter`, `metal_cut_out`. |
| `ai_design.customiser_id` | integer or null | no |  |
| `ai_design.files` | array of object | yes | The SVG, EPS, PDF, preview and face files only when status is delivered, and the uploaded source and its preview for every status. |
| `ai_design.files[].kind` | string | yes | One of: `svg`, `eps`, `illustrator_pdf`, `raster_preview`, `face_svg`, `source`, `source_preview`. |
| `ai_design.files[].purpose` | string | yes |  |
| `ai_design.files[].media_type` | string | yes |  |
| `ai_design.files[].access` | string | yes | One of: `private`, `public`. |
| `ai_design.files[].download_url` | string or null | no | A URL that needs no login. For a private file of an api design it is a revocable Sign Customiser link. For a public file it is the public storage URL, which cannot be revoked. Null for every other private file. |
| `ai_design.product_ids` | array of integer | yes |  |
| `ai_design.order_ids` | array of integer | yes |  |
| `ai_design.quote_id` | integer or null | no |  |
| `ai_design.quote_file` | object or null | no | The quote file the design was converted from, or null. |
| `ai_design.quote_file.field_id` | string | yes |  |
| `ai_design.quote_file.file_index` | integer | yes |  |
| `ai_design.ai_sign_design_job_id` | string or null | no |  |
| `ai_design.feedback_rating` | string or null | no | One of: `thumbs_up`, `thumbs_down`. |
| `ai_design.created_at` | string | yes |  |
| `idempotent_replay` | boolean | no | True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again. |
| `dry_run` | boolean | no | Present and true only when dry_run was requested. |
| `valid` | boolean | no | Present only on a dry run, and always true: a failing dry run returns a tool error instead. |
| `verdict` | object | no | Present only on a dry run: the design already made from the file or null, the credits the conversion would hold (1, or 0 for a file converted before) and the credits available now. |
| `verdict.operation` | string | no |  |
| `verdict.ai_design_id` | integer or null | no |  |
| `verdict.required_units` | integer | no |  |
| `verdict.available_units` | integer | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `ai_sign_design_capacity_reached` | The most designs that can run at the same time are running. Wait retry_after seconds and send the identical call again. |
| `ai_sign_design_erased` | The file was converted before and that design was erased. A file is converted once. Do not retry. |
| `ai_sign_designer_unavailable` | The AI sign designer cannot start designs for this store now. Nothing was held. |
| `confirmation_required` | Send confirm: true after the merchant agrees to spend one credit. |
| `idempotency_key_conflict` | The key was used for another quote file. Confirm the new conversion again with a new key. |
| `insufficient_credits` | The store has no available credit. Nothing was held. |
| `insufficient_scope` | The connection was approved without ai_sign_designs:write or without quotes:read. |
| `quote_file_not_convertible` | The file is not a PNG, JPEG, WebP, AVIF, SVG or PDF within the source limits. Nothing was held. Do not retry with this file. |
| `quote_file_not_found` | The quote has no file with this field_id and file_index. Read the quote with get_quote and use one of its files. |
| `quote_redacted` | The shopper data in the quote was erased, so its files cannot be converted. Nothing was held. Do not retry. |
| `rate_limited` | This connection started too many designs in the last minute. Wait retry_after seconds. |
| `resource_not_found` | The quote does not exist for this store. |
| `validation_failed` | field_id or file_index is missing or has the wrong type. |

## Example: Convert the first artwork file of a quote

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_quote_ai_design",
    "arguments": {
      "quote_id": 8123,
      "field_id": "field_artwork",
      "file_index": 0,
      "confirm": true,
      "max_credits": 1,
      "idempotency_key": "4b8e1f2a-7c3d-4e9a-b5f6-0d1c2e3f4a5b"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "ai_design": {
        "id": 51234,
        "origin": "quote",
        "status": "processing",
        "product_family": "neon",
        "customiser_id": 42,
        "files": [
          {
            "kind": "source",
            "purpose": "source",
            "media_type": "image/png",
            "access": "private",
            "download_url": null
          }
        ],
        "product_ids": [],
        "order_ids": [],
        "quote_id": 8123,
        "quote_file": {
          "field_id": "field_artwork",
          "file_index": 0
        },
        "ai_sign_design_job_id": null,
        "feedback_rating": null,
        "created_at": "2026-10-20T09:32:00Z"
      },
      "idempotent_replay": false
    }
  }
}
```

## Example: Check a conversion as a dry run

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_quote_ai_design",
    "arguments": {
      "quote_id": 8123,
      "field_id": "field_artwork",
      "file_index": 0,
      "dry_run": true
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "dry_run": true,
      "valid": true,
      "verdict": {
        "operation": "create",
        "ai_design_id": null,
        "required_units": 1,
        "available_units": 24
      }
    }
  }
}
```

## Example: Without confirmation no credit is held (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_quote_ai_design",
    "arguments": {
      "quote_id": 8123,
      "field_id": "field_artwork",
      "file_index": 0,
      "confirm": false,
      "max_credits": 1,
      "idempotency_key": "4b8e1f2a-7c3d-4e9a-b5f6-0d1c2e3f4a5b"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "This conversion holds one credit of the store and sends the quote file to external AI image providers.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}
```

## Example: A quote whose shopper data was erased (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_quote_ai_design",
    "arguments": {
      "quote_id": 8123,
      "field_id": "field_artwork",
      "file_index": 0,
      "confirm": true,
      "max_credits": 1,
      "idempotency_key": "4b8e1f2a-7c3d-4e9a-b5f6-0d1c2e3f4a5b"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "quote_redacted",
        "title": "Quote erased",
        "detail": "The shopper's data in this quote was erased, so its files cannot be converted. Nothing was reserved. Do not retry.",
        "recovery": "The shopper data in this quote was erased, so its files cannot be converted. Nothing was held. Do not retry."
      }
    }
  }
}
```
