Designs

Make jewelry designs from what a customer describes in words. Your server sends the description and gets the design's id at once. About 30 seconds later the design has its images, usually four, and you fetch them by that id. Both calls take your API key and the customer's access token from Auth. Each design belongs to that customer, in your store. The API comes with the Retail plan.

Create a design

Starts the design and answers within a few seconds, before the images exist.

POSThttps://api.diamra.com/v1/designs

Header	What it is
Authorization	Required. `Bearer` and your API key.
Diamra-Customer-Token	Required. The customer's `access_token` from Log in, Register or Refresh.

Parameter	What it is
prompt	Required. The piece the customer wants, in their words, up to 1,000 characters.

RequestShell

curl https://api.diamra.com/v1/designs \
  -H "Authorization: Bearer $DIAMRA_API_KEY" \
  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A rose gold ring with an oval sapphire and a thin pavé band" }'

ResponseHTTP

HTTP/2 202
content-type: application/json
request-id: req_5c0e2b8a41f97d36

{
  "id": "3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90",
  "status": "processing",
  "images": []
}

Retrieve a design

Answers the design with its images once they are ready. Send the same two headers. Ask every few seconds until the status is no longer processing: most designs take about 30 seconds, and some take up to two minutes.

GEThttps://api.diamra.com/v1/designs/{id}

RequestShell

curl https://api.diamra.com/v1/designs/3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90 \
  -H "Authorization: Bearer $DIAMRA_API_KEY" \
  -H "Diamra-Customer-Token: $ACCESS_TOKEN"

ResponseHTTP

HTTP/2 200
content-type: application/json
request-id: req_2e9b47d1a0c35f68

{
  "id": "3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90",
  "status": "succeeded",
  "images": [
    { "url": "https://yrhslqqtzvvlsgnoegue.supabase.co/storage/v1/object/public/design-images/3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90/0.webp" },
    { "url": "https://yrhslqqtzvvlsgnoegue.supabase.co/storage/v1/object/public/design-images/3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90/1.webp" },
    { "url": "https://yrhslqqtzvvlsgnoegue.supabase.co/storage/v1/object/public/design-images/3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90/2.webp" },
    { "url": "https://yrhslqqtzvvlsgnoegue.supabase.co/storage/v1/object/public/design-images/3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90/3.webp" }
  ]
}

The design

Both calls answer it.

Field	What it is
id	The design's id.
status	`processing` while the images are made, then `succeeded` or `failed`.
images	Once the design has succeeded, its images in order, usually four. Empty before that, and when it failed.
images[].url	A public link to a square WebP image, which you can show on your website.

When a design fails, create it again. Some descriptions can't be made into a design, so if it fails a second time, ask the customer to describe the piece another way.

Your store's settings

What you set for your store in your Bench applies to every design made through the API:

The Instructions and Engraving under Branding go into every design, and Watermark Designs, when it's on, puts your logo on the images.
The Per-user quota under Billing caps how many designs one customer can make in 24 hours.
If your store approves new customers first, a customer you haven't approved yet gets 403 access_pending.

Limits

One customer

10 designs in 10 seconds, and your Per-user quota in 24 hours.

Over a limit, the POST answers a 429: rate_limit for too many designs in a short time, customer_quota once the customer has used your quota. When the wait is known, a Retry-After header gives it in seconds.

Errors

Answer	When
400 parameter_missing	No prompt, or an empty one.
400 parameter_unknown	A parameter the call doesn't take, often a typo. param names it.
400 parameter_invalid	The prompt isn't a string, or is longer than 1,000 characters.
401 api_key_invalid	No key, or one Diamra doesn't know. See API keys.
401 api_key_revoked	The key was revoked in your console.
401 customer_token_invalid	No access token, or one that ran out or was never valid. Refresh the session, or log the customer in again.
403 access_pending	Your store approves new customers first and hasn't approved this one. Approve them under Customers in your Bench.
403 plan_required	Your store isn't on the Retail plan. Its keys work again once it is.
404 resource_missing	No design with this id belongs to this customer in your store.
429 customer_quota	The customer has made as many designs in 24 hours as your Per-user quota allows. Retry-After says when they can make more.
429 rate_limit	Too many designs in a short time.
503	The design couldn't be started. Try again in a minute.

An errorHTTP

HTTP/2 429
content-type: application/json
retry-after: 10800
request-id: req_7a1d3e95c02b4f86

{
  "error": {
    "type": "invalid_request_error",
    "code": "customer_quota",
    "message": "This customer has made as many designs as your store allows one customer in 24 hours."
  }
}