Images

Keep a photo of a piece your customer likes, so their designs can follow it. Your server sends the photo, or a link to it, and gets the image's id. Name the image by that id in reference_images when you create a design. The call takes your API key and the customer's access token from Auth. Each image belongs to that customer, in your store.

Create an image

Send the photo as a file in a multipart/form-data body, or a link to it in a JSON body. The image is ready for a design as soon as the call answers.

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

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
file	The photo: JPEG, PNG, GIF, WebP or HEIC, up to 10 MB, as the one field of a `multipart/form-data` body.
url	Or a public https link to the photo, in a JSON body. Send one of the two.

Upload a fileShell

curl https://api.diamra.com/v1/images \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \  -F file=@ring.jpg

Send a linkShell

curl https://api.diamra.com/v1/images \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com/photos/ring.jpg"  }'

ResponseHTTP

HTTP/2 201content-type: application/jsonrequest-id: req_6d2a9f40b1c87e53{  "id": "7c2e9a41-5d3b-4f8e-a1c6-0b9d4e2f8a73",  "url": "https://assets.diamra.com/store-images/5b8e1f3a-2c47-4d9e-b061-7a3f9c2e4d18/user-uploads/7c2e9a41-5d3b-4f8e-a1c6-0b9d4e2f8a73.webp"}

The image

Field	What it is
id	The image's id. Send it as `{ "id": "…" }` in `reference_images` when you create a design.
url	A public link to the image as Diamra keeps it: a WebP, 1,024 pixels at most on its longer side. It needs no key and never changes. Like a design's images, it is on assets.diamra.com.

Links

Diamra downloads a link once, when you send it, and keeps its own copy, so the image stays the same if the page it came from changes. The link must open without signing in. Diamra follows up to three redirects. It never fetches a link to an IP address or a local network name.

Use it in a design

Send up to three images in reference_images, each as an object with its id, with or without a prompt. The design stays close to the piece in the photos and changes what the prompt asks for. Only the customer who sent an image can use it, and only in your store.

A design from an imageShell

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": "The same ring in yellow gold",    "reference_images": [      {        "id": "7c2e9a41-5d3b-4f8e-a1c6-0b9d4e2f8a73"      }    ]  }'

Limits

Your store

60 images a minute.

Over it, the call answers a 429 rate_limit, with Retry-After: 60.

Errors

Answer	When
400 parameter_missing	No file and no url.
400 parameter_unknown	A field or parameter the call doesn't take, often a typo. param names it.
400 parameter_invalid	The url isn't a public https link.
400 image_unsupported	The file, or what the link answered, isn't a JPEG, PNG, GIF, WebP or HEIC image. param says which.
400 image_unreachable	Diamra couldn't download an image from the link. The host answered an error or nothing, or its redirects went past three or to an address Diamra doesn't fetch.
413 image_too_large	The file is over 10 MB. For a link over 10 MB the answer is 400, with the same code.
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.
429 rate_limit	More than 60 images in a minute from your store.
503	The image couldn't be saved. Try again in a minute.

An errorHTTP

HTTP/2 400content-type: application/jsonrequest-id: req_4f7b0e2d93a16c58{  "error": {    "type": "invalid_request_error",    "code": "image_unreachable",    "message": "We couldn't download an image from this url. Check that it opens without signing in.",    "param": "url"  }}