> ## Documentation Index
> Fetch the complete documentation index at: https://www.recraft.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Image inputs and results

How images are passed to the Recraft API and how generated images are returned.

## Image inputs

Every endpoint that takes an image (or mask) as input accepts the request in **two interchangeable formats**:

* **`multipart/form-data`** — upload the binary file directly using form fields (`image`, `mask`, `file`, ...). This is convenient for local files.
* **`application/json`** — pass the image *by reference* instead of uploading bytes. Each file field has a JSON counterpart that accepts a **public URL** or a **[data URL](https://developer.mozilla.org/en-US/docs/Web/URI/Schemes/data)** (a `data:image/...;base64,...` string).

The mapping between the multipart file fields and their JSON counterparts:

| Multipart field    | JSON field             | Type                                                               | Endpoints                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------ | ---------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`            | `image_url`            | string — URL or data URL of the input image                        | [Image to image](/docs/api-reference/endpoints#image-to-image)<br />[Image inpainting](/docs/api-reference/endpoints#image-inpainting)<br />[Image outpainting](/docs/api-reference/endpoints#image-outpainting)<br />[Replace background](/docs/api-reference/endpoints#replace-background)<br />[Generate background](/docs/api-reference/endpoints#generate-background)<br />[Erase region](/docs/api-reference/endpoints#erase-region)<br />[Remix image](/docs/api-reference/endpoints#remix-image) |
| `mask`             | `mask_url`             | string — URL or data URL of the mask image                         | [Image inpainting](/docs/api-reference/endpoints#image-inpainting)<br />[Generate background](/docs/api-reference/endpoints#generate-background)<br />[Erase region](/docs/api-reference/endpoints#erase-region)                                                                                                                                                                                                                                                                     |
| `file`             | `image_url`            | string — URL or data URL of the input image                        | [Vectorize image](/docs/api-reference/endpoints#vectorize-image)<br />[Remove background](/docs/api-reference/endpoints#remove-background)<br />[Crisp upscale](/docs/api-reference/endpoints#crisp-upscale)<br />[Creative upscale](/docs/api-reference/endpoints#creative-upscale)                                                                                                                                                                                                      |
| `files`            | `image_urls`           | array of strings — URLs or data URLs of the input images           | [Create style](/docs/api-reference/endpoints#create-style)                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `style_references` | `style_reference_urls` | array of strings — URLs or data URLs of the style reference images | [Generate image](/docs/api-reference/endpoints#generate-image)                                                                                                                                                                                                                                                                                                                                                                                                             |

All other parameters are identical between the two formats. Use JSON when your image is already hosted somewhere (just send the URL) or when a JSON body fits your client better; use multipart to upload local files directly.

### Examples

Generate an image with a style reference passed as a file and as a URL:

#### `multipart/form-data`

<CodeGroup>
  ```python Python theme={null}
  response = client.post(
      path='/images/generations',
      cast_to=object,
      options={'headers': {'Content-Type': 'multipart/form-data'}},
      body={'prompt': 'product hero shot, bottle on a table'},
      files={'style_references': open('reference.png', 'rb')},
  )
  print(response['data'][0]['url'])
  ```

  ```bash cURL theme={null}
  curl -X POST https://external.api.recraft.ai/v1/images/generations \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -H "Content-Type: multipart/form-data" \
    -F "prompt=product hero shot, bottle on a table" \
    -F "style_references=@reference.png"
  ```
</CodeGroup>

#### `application/json`

<CodeGroup>
  ```python Python theme={null}
  response = client.images.generate(
      prompt='product hero shot, bottle on a table',
      extra_body={'style_reference_urls': ['https://example.com/reference.png']},
  )
  print(response.data[0].url)
  ```

  ```bash cURL theme={null}
  curl -X POST https://external.api.recraft.ai/v1/images/generations \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "product hero shot, bottle on a table",
      "style_reference_urls": ["https://example.com/reference.png"]
    }'
  ```
</CodeGroup>

## Image results

Every endpoint that returns images takes the `response_format` parameter:

* **`url`** (default) — a JSON response, every image carries a `url` to download it from.
* **`b64_json`** — a JSON response, every image carries its bytes Base64-encoded in `b64_json`.
* **`multipart`** — a `multipart/form-data` response. The `response` part carries the same JSON with an `image_id` per image, followed by one part per image with the raw bytes. The part is named by the `image_id`, which is also in its `Content-ID` header, and its `Content-Type` is the image media type (`image/png`, `image/webp` or `image/svg+xml`).

<Note>
  For the best latency use `response_format: multipart`.
</Note>

Errors keep their JSON body and non-200 status with every `response_format`. The OpenAI Python library only reads JSON responses, so use `url` or `b64_json` with it and a plain HTTP client for `multipart`.

### Examples

#### `url`

<CodeGroup>
  ```python Python theme={null}
  response = client.images.generate(
      prompt='race car on a track',
  )
  print(response.data[0].url)
  ```

  ```bash cURL theme={null}
  curl -X POST https://external.api.recraft.ai/v1/images/generations \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "race car on a track"
    }'
  ```
</CodeGroup>

#### `b64_json`

<CodeGroup>
  ```python Python theme={null}
  import base64

  response = client.images.generate(
      prompt='race car on a track',
      response_format='b64_json',
  )
  with open('image.png', 'wb') as f:
      f.write(base64.b64decode(response.data[0].b64_json))
  ```

  ```bash cURL theme={null}
  curl -X POST https://external.api.recraft.ai/v1/images/generations \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "race car on a track",
      "response_format": "b64_json"
    }'
  ```
</CodeGroup>

#### `multipart`

<CodeGroup>
  ```python Python theme={null}
  import json

  import requests
  from requests_toolbelt.multipart import decoder

  response = requests.post(
      'https://external.api.recraft.ai/v1/images/generations',
      headers={'Authorization': f'Bearer {RECRAFT_API_TOKEN}'},
      json={'prompt': 'race car on a track', 'response_format': 'multipart'},
  )
  response.raise_for_status()

  result, images = None, {}
  for part in decoder.MultipartDecoder.from_response(response).parts:
      image_id = part.headers.get(b'Content-ID')
      if image_id is None:
          result = json.loads(part.content)
      else:
          images[image_id.decode()] = part.content

  for image in result['data']:
      with open(f"{image['image_id']}.png", 'wb') as f:
          f.write(images[image['image_id']])
  ```

  ```bash cURL theme={null}
  curl -X POST https://external.api.recraft.ai/v1/images/generations \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "race car on a track",
      "response_format": "multipart"
    }' \
    --output response.multipart
  ```
</CodeGroup>