--- title: "Create Scene Api" method: POST path: "/v1/scene/create" tags: ["Image"] --- # Create Scene Api `POST /v1/scene/create` 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`) ## Request body - SceneCreateAPIIn - `output` union — 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. - SceneCreateAPIOutputIn - `number_of_images` integer — Number of images to create. By default 4 images will be created. - `destination` string, uri — 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. - `format` union — Converts images to one of the following formats: `"jpeg"`, `"png"`, `"webp"`, `"avif"`. Selecting *Jpeg Options* allows to specify quality. - 'jpeg' | 'png' | 'webp' | 'avif' | 'tiff' — Converts the image into specified format. Examples: `"jpeg"`, `"png"`. - FormatJpegOptions - `type` 'jpeg', required — Must have value `"jpeg"` - `quality` integer - `progressive` boolean — Progressive JPEG loads in a browser in successive waves until a clear picture is formed. This improves image's loading speed. - FormatPngOptions - `type` 'png', required — Must have value `"png"` - `compression` 'fast' | 'best' | 'optimal' — Indicates compression effort. | Value | Description | | --- | --- | | `"fast"` | Used to apply minimum compression resulting in a bigger image size but less processing time.| | `"best"` | Used to apply maximum compression resulting in a smaller image size but more processing time.| | `"optimal"` | DEFAULT. Used to balance between compression effort and the processing time.| - FormatWebpOptions - `type` 'webp', required — Must have value `"webp"` - `compression` union — The WEBP codec supports both lossless and lossy modes of operation, so you can select the one that is appropriate for your goals. Lossy compression allows you to reduce the size of the image significantly in exchange for some loss of data, reducing the quality of an image. You can specify the amount of loss you are willing to accept. By default it's set to to 75. Lossless compression allows you to save maximum image details in exchange for a significantly increased file size. - 'lossy' | 'lossless' — Selects the WEBP compression type: | Value | Description | | --- | --- | | `"lossy"` | Lossy compression allows you to reduce the size of the image significantly in exchange for some loss of data, reducing the quality of an image.| | `"lossless"` | Lossless compression allows you to save maximum image details in exchange for a significantly increased file size.| - WebpLossyCompressionOptions - … - WebpLosslessCompressionOptions - … - FormatAvifOptions - `type` 'avif', required — Must have value `"avif"` - `compression` union — The AVIF codec supports both lossless and lossy modes of operation, so you can select the one that is appropriate for your goals. Lossy compression allows you to reduce the size of the image significantly in exchange for some loss of data, reducing the quality of an image. You can specify the amount of loss you are willing to accept. Lossless compression allows you to save maximum image details in exchange for a significantly increased file size. - 'lossy' | 'lossless' — Selects the AVIF compression type: | Value | Description | | --- | --- | | `"lossy"` | Lossy compression allows you to reduce the size of the image significantly in exchange for some loss of data, reducing the quality of an image.| | `"lossless"` | Lossless compression allows you to save maximum image details in exchange for a significantly increased file size.| - AvifLossyCompressionOptions - … - AvifLosslessCompressionOptions - … - string, uri - `object` union, required — Manipulate object on the scene so that the output images meet your requirements. - SceneCreateAPIObjectAbsoluteIn - `image_url` string, uri, required — URL of the input image. Should be from 1 to 4096 characters. Image must be accessible by our system. For better results, the background of the image should be transparent. - `placement_type` 'absolute' — `"absolute"` placement type allows to manually specify the absolute position, scale, and rotation degree of the object on a scene. - `rotation_degree` union — Degree of object rotation on the scene. By default, the object is not rotated. (i.e. 0.0). - number - integer - `scale` union — Relative object scale in relation to the scene. By default, the object is scaled to the scene edges. (i.e. 1.0). - integer - number - `position` ObjectPosition - `x` number — Relative position on the scene, where 0 is the left edge of the image and 1 is the right edge of the image. - `y` number — Relative position on the scene, where 0 is the bottom edge of the image and 1 is the top edge of the image. - SceneCreateAPIObjectOriginalIn - `image_url` string, uri, required — URL of the input image. Should be from 1 to 4096 characters. Image must be accessible by our system. For better results, the background of the image should be transparent. - `placement_type` 'original', required — `"original"` placement type instructs to use an object position and scale from the input image, meaning this placement method is fully automated and does not require any additional parameters. - SceneCreateAPIObjectPaddingIn - `image_url` string, uri, required — URL of the input image. Should be from 1 to 4096 characters. Image must be accessible by our system. For better results, the background of the image should be transparent. - `placement_type` 'padding', required — `"padding"` placement type allows to add a space around the object equally to each of 4 sides, or for height&width separately. - `padding` string, required — Add a space around the object equally to each of 4 sides, or for height&width separately. Can not be bigger than half of image width/height. - `scene` union, required — Customize the scene so that the output images meet your requirements. - SceneCreateAPISceneBackgroundEffectIn - `model` 'v1' | 'v2-beta' | 'v2' — An enumeration. - `effect` 'shadows', required — Selects the scene effect. | Value | Description | | --- | --- | | `"shadows"` | Apply shadow generation on the image.| - `color` union — Color as a hexadecimal. - string — Color as a hexadecimal. Examples: `"#ffffff"`, `"#000000"`. - 'transparent' — Makes the background of the image transparent, only works for `"png"` output format. - `view` 'auto' | 'top' | 'front' — Selects the template view direction. | Value | Description | | --- | --- | | `"top"` | The view is top-down, looking down on the scene from above.| | `"front"` | The view is horizontal, looking directly on the scene.| | `"auto"` | The view is automatically selected.| - `aspect_ratio` '21:9' | '1:1' | '4:3' | '3:2' | '2:3' | '5:4' | '4:5' | '3:4' | '16:9' | '9:16' — Aspect ratios supported by scene generation (both creative and high-precision modes) - SceneCreateAPIScenePromptIn - `model` 'v1' | 'v2-beta' | 'v2' — An enumeration. - `prompt` union, required — Text prompt that will be used to create the scene. Should be from 3 to 2048 characters. - string - ScenePromptAdvancedIn - `text` string — Text prompt that will be used to create the scene. Should be from 3 to 2048 characters. - `generate` boolean — If `true`, the prompt will be generated automatically based on the input image.By default, the prompt is not auto-generated. If `true`, the `text` is not allowed. - `guidelines` string — Guidelines for prompt generation. Only available when `generate` is `true`. - `negative_prompt` string — Text prompt that will exclude things from the scene. Should be from 3 to 2048 characters. - `steps` integer — The more inference steps you use, the better the results, but the more steps, the longer it takes to generate. If you want faster results, you can use fewer steps. If you want higher-quality results, you can use more steps. By default each `template_mode` has an optimal `steps` value. - `color` string — Color as a hexadecimal. Examples: `"#ffffff"`, `"#000000"`. - `aspect_ratio` '21:9' | '1:1' | '4:3' | '3:2' | '2:3' | '5:4' | '4:5' | '3:4' | '16:9' | '9:16' — Aspect ratios supported by scene generation (both creative and high-precision modes) - `preference` 'fast' | 'optimal' | 'best' — Preference control allows you to balance between generation speed and output image quality. Higher speed decreases image quality but enables quicker experimentation to find the best parameters for your background. | Value | Description | | --- | --- | | `"fast"` | Faster generation, lower quality.| | `"optimal"` | Balance between speed and quality.|| `"best"` | Highest quality, slower generation.| - SceneCreateAPISceneTemplateIn - `model` 'v1' | 'v2-beta' | 'v2' — An enumeration. - `template_mode` 'transform' | 'lock' | 'adjust' — Selects how closely the result should match the template. | Value | Description | | --- | --- | | `"transform"` | Template is transformed according to the prompt and color.| | `"adjust"` | Template is slightly adjusted to the product and prompt.|| `"lock"` | Template is preserved with maximum detail.| - `template_url` string, uri, required — URL of the input image. Should be from 1 to 4096 characters. Image must be accessible by our system. Is optional, if `prompt` is specified. - `color` string — Color as a hexadecimal. Examples: `"#ffffff"`, `"#000000"`. - `view` 'top' | 'front', required — Selects the template view direction. | Value | Description | | --- | --- | | `"top"` | The view is top-down, looking down on the scene from above.| | `"front"` | The view is horizontal, looking directly on the scene.| - `prompt` union — Text prompt that will be used to create the scene. Should be from 3 to 2048 characters. - string - ScenePromptAdvancedIn - `text` string — Text prompt that will be used to create the scene. Should be from 3 to 2048 characters. - `generate` boolean — If `true`, the prompt will be generated automatically based on the input image.By default, the prompt is not auto-generated. If `true`, the `text` is not allowed. - `guidelines` string — Guidelines for prompt generation. Only available when `generate` is `true`. - `negative_prompt` string — Text prompt that will exclude things from the scene. Should be from 3 to 2048 characters. - `steps` integer — The more inference steps you use, the better the results, but the more steps, the longer it takes to generate. If you want faster results, you can use fewer steps. If you want higher-quality results, you can use more steps. By default each `template_mode` has an optimal `steps` value. ## Response `200` Successful Response - ResponseScenePipelineResponseOut — Wrapper for responses - `data` ScenePipelineResponseOut - `input` PipelineInputObject, required - `ext` string, required — File extension. Can have values: `"jpg"`, `"png"`, `"avif"` - `mps` number, required — Megapixel count - `mime` string, required — MIME type (also known as ‘media type’) - `format` string, required — File format. Can have values: `"jpeg"`, `"png"`, `"avif"` - `width` integer, required — Image width in pixels - `height` integer, required — Image height in pixels - `output` PipelineOutputObject[], required - `ext` string, required — File extension. Can have values: `"jpg"`, `"png"`, `"avif"` - `mps` number, required — Megapixel count - `mime` string, required — MIME type (also known as ‘media type’) - `format` string, required — File format. Can have values: `"jpeg"`, `"png"`, `"avif"` - `width` integer, required — Image width in pixels - `height` integer, required — Image height in pixels - `tmp_url` string — Temporal URL of a processed image - `object_key` string — Path to a processed image in a bucket - `object_bucket` string — Bucket name - `object_uri` string — URI of a processed image in a bucket - `claid_storage_uri` string — URI of a processed image in a storage - `profiling` object ## Other responses - `401` — Authorization is required. - `402` — No API calls left. - `403` — Not enough permissions. - `422` — Unprocessable Entity. - `429` — Too many requests. --- [API](https://skmtc.net/claid/apis/claid-rest-api.md) · [All operations](https://skmtc.net/claid/apis/claid-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/claid/claid-rest-api/revisions/410fc0db9665/schema)