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": {
    "model": "v1" | "v2",
    "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
      } |
      {
        "generate": true,
        "guidelines": "real life setting"
      },
    "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",
    "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

OAuth2PasswordBearerOAuth2PasswordBearer

OAuth2passwordRequired

To work with the Claid API, send requests over HTTPS and authenticate using the Authorization header in the following format:Authorization: Bearer <YOUR_API_KEY>. You do not need to provide a password.

To get your API key, sign in to your Claid account and click Create API key button from the Overview or API keys pages.

Claid API’s base URL is https://api.claid.ai/v1/. All available endpoints are listed in the Storage and Image sections.

Bearer

This API uses OAuth 2.0 bearer token (API key) to authorize requests.

Token URL:

Body

application/json

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

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

/v1/scene/create

HTTPcURLJavaScriptPython

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

{
  "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": {
    "model": "v1",
    "effect": "shadows",
    "color": "text",
    "view": "auto",
    "aspect_ratio": "1:1"
  }
}

{
  "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/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

Read a response

Once you have made the request to https://api.claid.ai/v1/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.