AI sign designer quickstart

Use this guide to make a sign design from an image with the AI sign designer. You can use the API or an AI agent. Each design that the AI sign designer delivers uses one credit. A design that fails uses no credit.

You need Bash, curl and jq for the API steps. Your image must be a PNG, JPEG or WebP file.

Before you start

• The AI sign design API must be available for your Store. If it is not available, each request in this guide gets a 404 response.
• Your Store must have one or more AI credits.
• The AI sign designer sends your image to external AI image providers to make the design.

1. Create a key

Open the Store in Sign Customiser. Go to Tools & Settings > API Tokens. Create a key with these scopes:

• ai_sign_designs:read
• ai_sign_designs:write

A key that you created before does not get these scopes. Create a new key. See Authentication and key lifecycle for more information about keys.

2. Set the base URL and key

set -o pipefail
: "${SIGN_CUSTOMISER_API_BASE:=https://web.signcustomiser.com}"
read -rsp "Sign Customiser API key: " SIGN_CUSTOMISER_API_KEY
printf '\n'
export SIGN_CUSTOMISER_API_BASE SIGN_CUSTOMISER_API_KEY

3. Read the capabilities

curl --fail-with-body --silent --show-error \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${SIGN_CUSTOMISER_API_KEY}" \
  "${SIGN_CUSTOMISER_API_BASE}/api/v3/ai-sign-design-capabilities" | jq

Make sure that data.available is true. data.credits.available_units shows the credits that you can use. data.source shows the image limits.

4. Declare the image

Tell the API the file name, the media type and the exact size in bytes. For a JPEG or WebP file, change content_type to image/jpeg or image/webp. The file must be 5,242,880 bytes or less. Each side must be 8,192 pixels or less. The image must have 16,777,216 pixels or less.

IMAGE=shopfront-logo.png
SOURCE=$(curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${SIGN_CUSTOMISER_API_KEY}" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data "$(jq -n --arg name "$IMAGE" --argjson size "$(wc -c < "$IMAGE")" \
    '{filename: $name, content_type: "image/png", byte_size: $size}')" \
  "${SIGN_CUSTOMISER_API_BASE}/api/v3/ai-sign-design-sources")
SOURCE_ID=$(jq -r '.data.id' <<<"$SOURCE")

The response contains data.upload_target. The target is valid for 10 minutes. Only the first response contains the target. If you lose it, declare the image again with a new Idempotency-Key.

5. Upload the image

Send the file to the target. Use the method and all the headers in upload_target.

HEADERS=()
while IFS= read -r HEADER; do
  HEADERS+=(--header "$HEADER")
done < <(jq -r '.data.upload_target.headers | to_entries[] | "\(.key): \(.value)"' <<<"$SOURCE")
curl --fail-with-body --silent --show-error \
  --request "$(jq -r '.data.upload_target.method' <<<"$SOURCE")" \
  "${HEADERS[@]}" \
  --upload-file "$IMAGE" \
  "$(jq -r '.data.upload_target.url' <<<"$SOURCE")"

The image stays available for a design for 24 hours.

6. Start the design

This step holds one credit. Set product_family to neon, channel_letter or metal_cut_out.

JOB=$(curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${SIGN_CUSTOMISER_API_KEY}" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data "$(jq -n --arg id "$SOURCE_ID" '{source_file: {id: $id}, product_family: "neon"}')" \
  "${SIGN_CUSTOMISER_API_BASE}/api/v3/ai-sign-design-jobs")
JOB_ID=$(jq -r '.data.id' <<<"$JOB")

The API gives an SVG, an EPS and an Illustrator-compatible PDF. To get only the SVG, add "output_formats": ["svg"].

An image can start one design only. If you send the same request again with the same Idempotency-Key, you get the same job. You do not use a second credit.

7. Wait for the design

Read the job until data.status is delivered or failed. Wait for the number of seconds in data.poll_after_seconds between each read.

while :; do
  JOB=$(curl --fail-with-body --silent --show-error \
    --header "Accept: application/json" \
    --header "Authorization: Bearer ${SIGN_CUSTOMISER_API_KEY}" \
    "${SIGN_CUSTOMISER_API_BASE}/api/v3/ai-sign-design-jobs/${JOB_ID}")
  STATUS=$(jq -r '.data.status' <<<"$JOB")
  case "$STATUS" in delivered | failed) break ;; esac
  sleep "$(jq -r '.data.poll_after_seconds // 5' <<<"$JOB")"
done
echo "$STATUS"

8. Download the files

Do this step only when STATUS is delivered. Each ready file in data.result.files has a download_url. This link needs no API key and no login. You can give it to a manufacturer.

curl --fail --location --silent --show-error \
  --output "${JOB_ID}.svg" \
  "$(jq -r '.data.result.files.svg.download_url' <<<"$JOB")"

• The files are not drawn at the physical size of the sign. Scale the artwork to data.result.assessed_dimensions.
• Read data.result.advisories before you send a design to production.

If the EPS or the PDF has state: failed, send POST /api/v3/ai-sign-design-jobs/{job_id}/exports with a new Idempotency-Key. This retry is free. Each job has 3 retries.

Use an AI agent

Claude Code and the OpenAI Codex and ChatGPT plugins can do the same steps with the hosted MCP server. Connect the agent with the connection guide. Approve View AI sign designs and Use the AI sign designer. If you connected the agent before, connect it again.

Then ask the agent to make a design from your image. The agent uses these tools:

1. get_ai_sign_design_capabilities
2. create_ai_sign_design_source, and then it uploads the image to the target
3. create_ai_sign_design_job
4. get_ai_sign_design_job
5. retry_ai_sign_design_job_exports, if a conversion fails

create_ai_sign_design_job uses a credit. The agent must send confirm: true and max_credits: 1. The agent gives you the download_url of each file.

When a request fails

See Errors and retries for all error responses.