Generate Images

Generate synthetic images for your Roboflow project.

To generate synthetic images, make a POST request to the following API endpoint:

POST https://api.roboflow.com/synthetic-image

The only supported models are OpenAI's generative image models. To use this endpoint, you will need to configure your third party OpenAI API key in Workspace Settings.

For requests with an image parameter we first send the image to the GPT-4 Vision model to generate an image description. The generative image prompt is a combination of the image description, the prompt parameter, and additional prompt keywords to make the image photorealistic.

You can find a Roboflow image ID with the search API, or by opening the image in Roboflow and copying the ID from the URL which is in this format:

https://app.roboflow.com/.../images/IMAGE_ID?...

Request Body

Generate synthetic images for use with Roboflow

POST https://api.roboflow.com/synthetic-image

Query Parameters

Name	Type	Description
api_key*	string	Roboflow API Key. SeeAuthentication for more details.

Request Body

Name	Type	Description
image_type	string	Specify type of image parameter. Required if image is present. Must be one of id, url, or base64.
image	string	Roboflow image ID, URL to image, or image base64.
project_url	string	Roboflow project to add generated image to. See How to Retrieve a Project ID and Version Number to learn how to retrieve your project url (also called project ID).
model	string	See OpenAI API reference. We default to dall-e-3.
style	string	See OpenAI API reference. We default to natural.
size	string	See OpenAI API reference. We default to 1024x1024.
prompt	string	A text description of the desired image(s).
quality	string	See OpenAI API reference. We default to hd.
n	number	See OpenAI API reference. We default to 1.
force_caption_regenerate	boolean	Disables caching for image descriptions. Only relevant for Roboflow images.
unmodified_prompt	boolean	Disables our prompt suffix that attempts to make the image photorealistic.

200: OK A list of OpenAI image objects.

See OpenAI API reference.

Examples

cURL

Generating an image based on a Roboflow image

curl -X POST "https://api.roboflow.com/synthetic-image?api_key=$ROBOFLOW_API_KEY" \
-H 'Content-Type: application/json' \
--data \
'{
    "image": "62MYRuqqWCRZ02q52vsY",
    "image_type": "id",
    "project_url": "fall-leaves",
    "prompt": "All trees have red leaves."
}'

Generating a new image from prompt

curl -X POST "https://api.roboflow.com/synthetic-image?api_key=$ROBOFLOW_API_KEY" \
-H 'Content-Type: application/json' \
--data \
'{
    "project_url": "fall-leaves",
    "prompt": "Image of a residential setting during fall with dominant maple trees showcasing intense orange leaves, the only color of tree leaf."
}'

Generating an image based on a local image (e.g., trees.png)

# Convert the image to base64
IMAGE_BASE64=$(openssl base64 -in trees.png)

# Create a temporary file
TEMP_FILE=$(mktemp)

# Write the JSON data to the temporary file
echo '{
    "image": "'"$IMAGE_BASE64"'",
    "image_type": "base64",
    "project_url": "fall-leaves",
    "prompt": "All trees have red leaves."
}' > $TEMP_FILE

# Use the temporary file as the data parameter in the curl command
curl -X POST "https://api.roboflow.com/synthetic-image?api_key=$ROBOFLOW_API_KEY" \
-H 'Content-Type: application/json' \
--data @${TEMP_FILE}

# Remove the temporary file
rm $TEMP_FILE

JavaScript

We're using axios to perform the POST request in this example so first run npm install axios to install the dependency.

Generating an image based on a Roboflow image

const axios = require("axios");

axios({
    method: "POST",
    url: "https://api.roboflow.com/synthetic-image",
    params: {
        api_key: "ROBOFLOW_API_KEY",
    },
    data: {
        image: "62MYRuqqWCRZ02q52vsY",
        image_type: "id",
        project_url: "fall-leaves",
        prompt: "All trees have red leaves."
    },
    headers: {
        "Content-Type": "application/json"
    }
})
.then(function(response) {
    console.log(response.data);
})
.catch(function(error) {
    console.log(error.message);
});

Generating a new image from prompt

const axios = require("axios");

axios({
    method: "POST",
    url: "https://api.roboflow.com/synthetic-image",
    params: {
        api_key: "ROBOFLOW_API_KEY",
    },
    data: {
        project_url: "fall-leaves",
        prompt: "Image of a residential setting during fall with dominant maple trees showcasing intense orange leaves, the only color of tree leaf."
    },
    headers: {
        "Content-Type": "application/json"
    }
})
.then(function(response) {
    console.log(response.data);
})
.catch(function(error) {
    console.log(error.message);
});

Generating an image based on a local image (e.g., trees.png)

const fs = require("fs");
const axios = require("axios");

// Read the image file and convert it to base64
const imageBase64 = fs.readFileSync("trees.png", { encoding: "base64" });

// Define the data for the POST request
const data = {
    image: imageBase64,
    image_type: "base64",
    project_url: "fall-leaves",
    prompt: "All trees have red leaves."
};

// Send the POST request
axios
    .post("https://api.roboflow.com/synthetic-image?api_key=ROBOFLOW_API_KEY", data, {
        headers: {
            "Content-Type": "application/json"
        }
    })
    .then((response) => {
        console.log(response.data);
    })
    .catch((error) => {
        console.error(error);
    });