API Reference

request and response description

Background Generation contract

Below, you can see all possible options for the request body. See the AI Background Options and Image generation I/O sections to learn more about Background Generation options.

{
  "output": {
    "destination": "storage://storage-name/path/"
    "number_of_images": 4,
    "format": "png" | "jpeg" | "webp" | "avif"
  },
  "object": {
    "image_url": "storage://storage-name/path/image.png",
    "placement_type": "absolute" | "original",
    "rotation_degree": 0,
    "scale": 1,
    "position": {
      "x": 0.5,
      "y": 0.5
    }
  },
  "scene": {
    "template_url": "storage://storage-name/path/template.png",
    "template_mode": "transform" | "adjust" | "lock",
    "color": "#aece8c",
    "view": "top" | "front",
    "prompt": "on the wooden table in the dark room" | {"generate": true}
    "negative_prompt": "watermark, low quality",
    "steps": 25,
    "aspect_ratio": "4:7" | "7:9" | "4:5" | "1:1" | "9:7" | "19:13" | "7:4" | "16:9" | "12:5",
    "model": "v1" | "v2",
    "preference": "fast" | "optimal" | "best"
  }
}

Create Scene Api

post

Specifies:

• object to place on the scene and its properties (object)
• scene properties (scene)
• how many images will be created and where they will be stored (output)

Authorizations

OAuth2PasswordBearer

Body

outputany ofOptional

URL of the output images. If output is not defined, we store the output image on our bucket and return the temporary URL. Images are stored for one day.

Default: {"number_of_images":4,"format":"png"}

or

string · uri · min: 1 · max: 4096Optional

objectany ofRequired

Manipulate object on the scene so that the output images meet your requirements.

or

sceneany ofRequired

Customize the scene so that the output images meet your requirements.

or

or

Responses

200

Successful Response

application/json

401

Authorization is required.

application/json

402

No API calls left.

application/json

403

Not enough permissions.

application/json

422

Unprocessable Entity.

application/json

429

Too many requests.

application/json

post

HTTPcURLJavaScriptPython

POST /v1-ea/scene/create HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 288

{
  "output": {
    "number_of_images": 4,
    "destination": "https://example.com",
    "format": "png"
  },
  "object": {
    "image_url": "storage://storage_1/path/image.jpg",
    "placement_type": "absolute",
    "rotation_degree": 0,
    "scale": 1,
    "position": {
      "x": 0.5,
      "y": 0.5
    }
  },
  "scene": {
    "effect": "shadows",
    "color": "text",
    "view": "top"
  }
}

{
  "data": {
    "input": {
      "ext": "text",
      "mps": 1,
      "mime": "text",
      "format": "text",
      "width": 1,
      "height": 1
    },
    "output": [
      {
        "ext": "text",
        "mps": 1,
        "mime": "text",
        "format": "text",
        "width": 1,
        "height": 1,
        "tmp_url": "text",
        "object_key": "text",
        "object_bucket": "text",
        "object_uri": "text",
        "claid_storage_uri": "text"
      }
    ],
    "profiling": {}
  }
}

Request

HTTP

POST /v1-ea/scene/create HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json

{
  "object": {
    "image_url": "https://images.claid.ai/photoshoot-templates/docs/product.png",
    "rotation_degree": 0.0,
    "scale": 0.55,
    "position": {
      "x": 0.35,
      "y": 0.5
    }
  },
  "scene": {
    "template_url": "https://images.claid.ai/photoshoot-templates/docs/scene.png",
    "template_mode": "transform",
    "view": "front",
    "prompt": "marble countertop, marble wall background, monochromatic, bokeh, closeup, professional product photography"
  },
  "output": {
    "number_of_images": 1,
    "format": "png"
  }
}

cURL

curl -X POST --location "https://api.claid.ai/v1-ea/scene/create" --http1.1 \
    -H "Host: api.claid.ai" \
    -H "Authorization: Bearer {YOUR_API_KEY}" \
    -H "Content-Type: application/json" \
    -d "{
      \"object\": {
        \"image_url\": \"https://images.claid.ai/photoshoot-templates/docs/product.png\",
        \"rotation_degree\": 0.0,
        \"scale\": 0.55,
        \"position\": {
          \"x\": 0.35,
          \"y\": 0.5
        }
      },
      \"scene\": {
        \"template_url\": \"https://images.claid.ai/photoshoot-templates/docs/scene.png\",
        \"template_mode\": \"transform\",
        \"view\": \"front\",
        \"prompt\": \"marble countertop, marble wall background, monochromatic, bokeh, closeup, professional product photography\"
      },
      \"output\": {
        \"number_of_images\": 1,
        \"format\": \"png\"
      }
    }"

Read a response

Once you have made the request to https://api.claid.ai/v1-ea/scene/create you will get a response with information about input text and output images.

Image information is shown in the response:

Parameter	Type	Description
ext	string	File extension. Will have png value
mps	integer	Megapixel count
mime	string	MIME type (also known as ‘media type’)
width	integer	Image width in pixels
height	integer	Image height in pixels
format	string	File format. Will have png value
tmp_url	string	Temporary URL of a processed image. Will be empty if output is specified

Response body

{
    "data": {
        "input": {
                "ext": "png",
		"mps": 1.817323,
		"mime": "image/png",
		"format": "PNG",
		"width": 773,
		"height": 2351
        },
        "output": [
            {
                "ext": "png",
                "mps": 1.048576,
                "mime": "image/png",
                "format": "PNG",
                "width": 1024,
                "height": 1024,
                "tmp_url": "https://dl.claid.ai/efca3eae-2eb5-4952-ae83-b300ce41ab90/4bede5530f994346a3ca52d4ae6631a0.png"
            },
            {
               "ext": "png",
                "mps": 1.048576,
                "mime": "image/png",
                "format": "PNG",
                "width": 1024,
                "height": 1024,
                "tmp_url": "https://dl.claid.ai/72226dad-8311-4927-9879-8bb4f3ca38c4/55ccc333e60e463d820e908c899348df.png"
            },
        ]
    }
}

Headers:

See the Request Headers and Response Headers to learn about headers.