Generate images

library(foundryR)

Calls to Azure show output recorded from a live run; setup code is shown but not run.

Use image generation when you need a reproducible visual stimulus or draft illustration and can keep the prompt, model, and saved output with your study materials.

The video functions are defunct because Azure retires its last Sora video model on 2026-10-15 with no replacement.

Configure image resources

Image models may live on the same Azure OpenAI resource as your text models, or on a separate resource. Use the image-specific helpers only when the image resource or key differs.

foundry_set_image_endpoint(Sys.getenv("AZURE_FOUNDRY_IMAGE_ENDPOINT"))
foundry_set_image_key("your-image-api-key")

Sys.setenv(AZURE_FOUNDRY_IMAGE_MODEL = "my-image-deployment")

Generate a research stimulus

This example creates a generic classroom stimulus for a survey experiment. It avoids real people, brands, and institution names so the image can be reviewed as a study asset rather than as a depiction of a real place.

image <- foundry_image(
  "A simple flat vector illustration of an empty classroom with desks, a chalkboard, and soft daylight, no people, no logos, no text",
  model = "gpt-image-2",
  size = "1024x1024",
  quality = "low",
  output_format = "jpeg",
  output_compression = 40
)

image[, c("prompt", "output_format", "created")]
#> # A tibble: 1 × 3
#>   prompt                                       output_format created            
#>   <chr>                                        <chr>         <dttm>             
#> 1 A simple flat vector illustration of an emp… jpeg          2026-09-27 20:28:45

gpt-image-2 returns the image as base64 data in the b64_json column, which foundry_save_image() decodes and writes to disk. The model does not return a revised prompt, so revised_prompt is NA, and your own prompt is the record of what you asked for.

Save and display the image

Save generated images before using them in a report, survey instrument, or audit trail.

img_path <- tempfile(fileext = ".jpeg")
suppressMessages(invisible(foundry_save_image(image, img_path)))
file.exists(img_path)
#> [1] TRUE

AI-generated flat vector illustration of an empty classroom with desks and a chalkboard

Make a controlled variant

Survey experiments often need two versions of one stimulus that differ in a single attribute. Generating each version from scratch changes the whole scene. foundry_image_edit() starts from the saved image, so the room, desks, and style carry over while the prompt changes one thing.

edited <- foundry_image_edit(
  image = img_path,
  prompt = paste(
    "Add stacks of papers and cardboard boxes on the desks.",
    "Keep the room, desks, chalkboard, light, and illustration style unchanged."
  ),
  model = "gpt-image-2",
  quality = "low",
  output_format = "jpeg"
)

edited_path <- tempfile(fileext = ".jpeg")
suppressMessages(invisible(foundry_save_image(edited, edited_path)))

Original stimulus: an empty, tidy classroom illustration Edited variant: the same classroom with papers and boxes stacked on the desks

Compare the pair before you field it. The edit model can change details you did not ask about, such as the light or the number of desks, and any unintended difference becomes part of the treatment.

Record what you used

For research stimuli, keep the prompt, deployment name, generation date, saved file, and any exclusion rules used in the prompt. For an edited variant, also keep the edit prompt and the file it started from. The tibbles returned by foundry_image() and foundry_image_edit() give you the prompt and timestamp; your study log should add the survey question or experimental condition that used each image.