---
title: "Generate Background"
method: POST
path: "/v1/images/generateBackground"
tags: ["image"]
---

# Generate Background

`POST /v1/images/generateBackground`

## Request

- Base URL: `https://external.api.recraft.ai`
- URL: `https://external.api.recraft.ai/v1/images/generateBackground`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/recraft/apis/recraft-ai-external-api/docs/v1/images/generateBackground/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- object
  - `controls` UserControls
    - `artistic_level` integer
    - `background_color` ImageColor
      - `rgb` integer[]
      - `std` number[]
      - `weight` number
    - `colors` ImageColor[]
      - `rgb` integer[]
      - `std` number[]
      - `weight` number
    - `no_text` boolean
  - `image_format` 'webp' | 'png'
  - `model` 'recraftv2' | 'recraftv2_raster' | 'recraftv2_vector' | 'recraftv3' | 'recraftv3_raster' | 'recraftv3_vector' | 'recraftv4' | 'recraftv4_raster' | 'recraftv4_vector' | 'recraftv4_pro' | 'recraftv4_pro_raster' | 'recraftv4_pro_vector' | 'recraftv4_1' | 'recraftv4_1_raster' | 'recraftv4_1_vector' | 'recraftv4_1_pro' | 'recraftv4_1_pro_raster' | 'recraftv4_1_pro_vector' | 'recraftv4_1_utility' | 'recraftv4_1_utility_raster' | 'recraftv4_1_utility_vector' | 'recraftv4_1_utility_pro' | 'recraftv4_1_utility_pro_raster' | 'recraftv4_1_utility_pro_vector' | 'recraftv4_styles' | 'recraftv4_styles_raster' | 'recraftv4_styles_vector' | 'recraftv4_styles_pro' | 'recraftv4_styles_pro_raster' | 'recraftv4_styles_pro_vector' | 'recraftv4_1_flash' | 'recraftv4_1_flash_raster'
  - `n` integer
  - `negative_prompt` string
  - `prompt` string, required
  - `random_seed` integer
  - `response_format` 'url' | 'b64_json' | 'multipart'
  - `style` string
  - `style_id` string, uuid
  - `style_match` 'regular' | 'precise' | 'flexible'
  - `text_layout` TextLayoutItem[]
    - `bbox` array[], required
      - number[]
    - `text` string, required
  - `zdr` boolean: Zero data retention: the prompt and the input and output image bytes are neither stored nor logged; only an output requested as a URL is uploaded so it can be served.
  - `image_url` string: URL or data URL of the input image. JSON counterpart of the `image` file.
  - `mask_url` string: URL or data URL of the mask image. JSON counterpart of the `mask` file.

## Response `200`

OK

- GenerateImageResponse
  - `created` integer, required
  - `credits` integer, required
  - `data` Image[], required
    - `b64_json` string
    - `image_id` string, uuid, required
    - `revised_prompt` string
    - `url` string
  - `style_id` string, uuid

## Other responses

- `4XX`: Request failed. The body is plain text (for example 401 `request unauthorized`) or JSON, so read it as text before parsing.
- `5XX`: Request failed. The body is plain text (for example 401 `request unauthorized`) or JSON, so read it as text before parsing.

---

[API](https://skmtc.dev/recraft/apis/recraft-ai-external-api.md) - [All operations](https://skmtc.dev/recraft/apis/recraft-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recraft/apis/recraft-ai-external-api/revisions/2180aa45c034?raw)