AI sign designs

Create an AI sign design job

Copy page

Starts one AI sign design from an uploaded source and answers 202 at once. Requires ai_sign_designs:write and an Idempotency-Key.

POST/api/v3/ai-sign-design-jobs

Create an AI sign design job

Starts one AI sign design from an uploaded source and answers 202 at once. Requires `ai_sign_designs:write` and an `Idempotency-Key`. The design runs in the background: poll `GET /api/v3/ai-sign-design-jobs/{job_id}` (the `Location` header) no more often than `poll_after_seconds`, until `status` is `delivered` or `failed`. Name the design context in one of two ways. For a standalone design, send `product_family`. For a design in one of your customisers, send `customiser_id`, and optionally one of its `letter_type_id`s. That also needs `customisers:read`: without it the create answers 403 `insufficient_scope` naming `customisers:read`. The family is the customiser's own: a different `product_family` answers 422 `product_family_conflict`. Credits: the job holds one credit before any work starts. A delivered design charges that credit, and a failed design releases it, so a failure costs nothing. `charge.state` reports `reserved`, `charged` or `released`. With no credit available the create answers 409 `insufficient_credits` with `required_units` and `available_units`, and nothing is reserved. The source is verified and used once. Its bytes are checked when the job starts; a failed check answers 422 `source_rejected` and the source cannot be used again. A source that another job used answers 409 `source_already_consumed`. A retry with the same `Idempotency-Key` and body returns the same job and charges nothing more. If the designer is busy this answers 429 `ai_sign_design_capacity_reached` with `Retry-After`; retry with the same key. While the AI sign designer is turned off, or design jobs cannot start for this store yet, this answers 503 `ai_sign_designer_unavailable` and nothing is reserved. `output_formats` chooses the files. It defaults to every format: `svg`, `eps` and `illustrator_pdf` (an Illustrator-compatible PDF, not a native Illustrator file). SVG is always made. Send `["svg"]` to skip the optional conversions. The source and every file the job makes are stored privately.

Create an AI sign design job

Overview

The design runs in the background: poll GET/api/v3/ai-sign-design-jobs/{job_id} (the Location header) no more often than poll_after_seconds, until status is delivered or failed. Name the design context in one of two ways. For a standalone design, send product_family. For a design in one of your customisers, send customiser_id, and optionally one of its letter_type_ids. That also needs customisers:read: without it the create answers 403 insufficient_scope naming customisers:read. The family is the customiser's own: a different product_family answers 422 product_family_conflict. Credits: the job holds one credit before any work starts. A delivered design charges that credit, and a failed design releases it, so a failure costs nothing. charge.state reports reserved, charged or released. With no credit available the create answers 409 insufficient_credits with required_units and available_units, and nothing is reserved. The source is verified and used once. Its bytes are checked when the job starts; a failed check answers 422 source_rejected and the source cannot be used again. A source that another job used answers 409 source_already_consumed. A retry with the same Idempotency-Key and body returns the same job and charges nothing more. If the designer is busy this answers 429 ai_sign_design_capacity_reached with Retry-After; retry with the same key. While the AI sign designer is turned off, or design jobs cannot start for this store yet, this answers 503 ai_sign_designer_unavailable and nothing is reserved. output_formats chooses the files. It defaults to every format: svg, eps and illustrator_pdf (an Illustrator-compatible PDF, not a native Illustrator file). SVG is always made. Send ["svg"] to skip the optional conversions. The source and every file the job makes are stored privately.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: ai_sign_designs:write

Request body

source_fileobjectbody

product_familystringbody

customiser_idintegerbody

letter_type_idintegerbody

output_formatsarraybody

Request body example

{
  "source_file": {
    "id": "aisrc_9f2c4b7ad13e6058ba41cd4201"
  },
  "product_family": "neon",
  "customiser_id": 16,
  "letter_type_id": 16,
  "output_formats": [
    "svg",
    "eps",
    "illustrator_pdf"
  ]
}

Create an AI sign design job

curl https://web.signcustomiser.com/api/v3/ai-sign-design-jobs \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_file": {
    "id": "aisrc_9f2c4b7ad13e6058ba41cd4201"
  },
  "product_family": "neon",
  "customiser_id": 16,
  "letter_type_id": 16,
  "output_formats": [
    "svg",
    "eps",
    "illustrator_pdf"
  ]
}'

{
  "data": {
    "object": "ai_sign_design_job",
    "id": "aijob_4k8m2p6r9t1v3x5z7b0d2f4h6j",
    "status": "queued",
    "product_family": "neon",
    "customiser_id": null,
    "letter_type_id": null,
    "source_file": {
      "id": "aisrc_9f2c4b7ad13e6058ba41cd4201",
      "media_type": "image/png",
      "byte_size": 184320,
      "width_px": 1600,
      "height_px": 900,
      "url": null,
      "download_url": null
    },
    "output_formats": [
      "svg",
      "eps",
      "illustrator_pdf"
    ],
    "poll_after_seconds": 5,
    "result": null,
    "charge": {
      "state": "reserved",
      "units": 1
    },
    "error": null,
    "created_at": "2026-10-20T09:32:00Z",
    "completed_at": null
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/ai-sign-design-jobs/aijob_4k8m2p6r9t1v3x5z7b0d2f4h6j",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key",
  "title": "Missing idempotency key",
  "status": 400,
  "code": "missing_idempotency_key",
  "detail": "Provide an Idempotency-Key header for this write.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key",
  "title": "Missing API key",
  "status": 401,
  "code": "missing_api_key",
  "detail": "Provide a store API key as a bearer token.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the ai_sign_designs:write scope.",
  "required_scopes": [
    "ai_sign_designs:write"
  ],
  "granted_scopes": [
    "ai_sign_designs:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found",
  "title": "Resource not found",
  "status": 404,
  "code": "resource_not_found",
  "detail": "The requested resource does not exist or does not belong to the authenticated store.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_credits",
  "title": "Insufficient credits",
  "status": 409,
  "code": "insufficient_credits",
  "detail": "A design job reserves 1 credit before it starts, and this store has 0 available. Nothing was reserved, and the source was not used. Add credits in the merchant admin, then retry with the same source.",
  "required_units": 1,
  "available_units": 0,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/source_already_consumed",
  "title": "Source already consumed",
  "status": 409,
  "code": "source_already_consumed",
  "detail": "Another design already used this source. A source starts one design only. Declare a new source for another design.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict",
  "title": "Idempotency key conflict",
  "status": 409,
  "code": "idempotency_key_conflict",
  "detail": "This Idempotency-Key was already used for a different request body on this operation.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "The request payload failed validation.",
  "errors": [
    {
      "pointer": "/product_family",
      "code": "unsupported_value",
      "detail": "The selected product family is invalid.",
      "allowed_values": [
        "neon",
        "channel_letter",
        "metal_cut_out"
      ]
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/product_family_conflict",
  "title": "Product family conflict",
  "status": 422,
  "code": "product_family_conflict",
  "detail": "The customiser makes neon signs, so product_family must be neon or omitted.",
  "errors": [
    {
      "pointer": "/product_family",
      "code": "product_family_conflict",
      "detail": "The customiser makes neon signs, so product_family must be neon or omitted.",
      "allowed_values": [
        "neon"
      ]
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/source_not_uploaded",
  "title": "Source not uploaded",
  "status": 422,
  "code": "source_not_uploaded",
  "detail": "No bytes have arrived for this source. PUT the file to the upload target from the create response, confirm that the source status is uploaded, then retry.",
  "errors": [
    {
      "pointer": "/source_file/id",
      "code": "source_not_uploaded",
      "detail": "The staged object does not exist."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/ai_sign_design_capacity_reached",
  "title": "AI sign design capacity reached",
  "status": 429,
  "code": "ai_sign_design_capacity_reached",
  "detail": "The most design jobs that can run at the same time are already running. Nothing was reserved, and the source was not used. Retry with the same Idempotency-Key and body after retry_after seconds.",
  "retry_after": 30,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/ai_sign_designer_unavailable",
  "title": "AI sign designer unavailable",
  "status": 503,
  "code": "ai_sign_designer_unavailable",
  "detail": "AI sign design jobs cannot start for this store yet. No credit was reserved and no work started. Sources and jobs that already exist stay readable. Read GET /api/v3/ai-sign-design-capabilities and try again when available is true.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}