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 (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 Image inpainting Image outpainting Replace background Generate background Erase region Remix image
`mask`	`mask_url`	string — URL or data URL of the mask image	Image inpainting Generate background Erase region
`file`	`image_url`	string — URL or data URL of the input image	Vectorize image Remove background Crisp upscale Creative upscale
`files`	`image_urls`	array of strings — URLs or data URLs of the input images	Create style
`style_references`	`style_reference_urls`	array of strings — URLs or data URLs of the style reference images	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`

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'])

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"

`application/json`

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)

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"]
  }'

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).

For the best latency use response_format: multipart.

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`

response = client.images.generate(
    prompt='race car on a track',
)
print(response.data[0].url)

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"
  }'

`b64_json`

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))

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"
  }'

`multipart`

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']])

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

​Image inputs

​Examples

​multipart/form-data

​application/json

​Image results

​Examples

​url

​b64_json

​multipart

Image inputs

Examples

`multipart/form-data`

`application/json`

Image results

Examples

`url`

`b64_json`

`multipart`