Skip to content

Using the OpenAI API

Learn how to use PhotoPrism with OpenAI's GPT-5 models to generate high-quality captions and labels for your pictures.

Setup

Prerequisites

  • In order to use OpenAI services, you need a valid API key, which can be configured via OPENAI_API_KEY or OPENAI_API_KEY_FILE.
  • PhotoPrism must also have network access to api.openai.com.

Configuration

Add the following caption and/or labels model configurations to your vision.yml file:

Models:
  - Type: caption
    Model: gpt-5-nano
    Engine: openai
    Run: newly-indexed
    Options:
      Detail: low           # optional: default is low
      MaxOutputTokens: 512  # optional: change token limit
    Service:
      Key: ${OPENAI_API_KEY}
  - Type: labels
    Model: gpt-5-mini
    Engine: openai
    Run: newly-indexed
    Options:
      MaxOutputTokens: 1024 # optional: change token limit
    Service:
      Key: ${OPENAI_API_KEY}

Recommendations:

  • Keep the model Name exactly as published by OpenAI so defaults apply correctly.
  • Service.Key can be omitted if OPENAI_API_KEY / _FILE is set in the environment.
  • Optional headers: set Service.Org and Service.Project when your account requires them.

By default, PhotoPrism uses the OpenAI Responses API endpoint at https://api.openai.com/v1/responses with a single 720 px thumbnail (detail: low).

Usage Tips

  • To avoid unexpected API costs, set Run: manual and run the models manually with the photoprism vision run command.
  • When you remove custom model configuration from you vision.yml file, the built-in default models will be enabled again.
  • When you need domain-specific wording, you may override System or Prompt in vision.yml; keep them short and retain the schema reminder for labels.

Troubleshooting

Verifying Your Configuration

If you encounter issues, a good first step is to verify how PhotoPrism has loaded your vision.yml configuration. You can do this by running: 

docker compose exec photoprism photoprism vision ls

This command outputs the settings for all supported and configured model types. Compare the results with your vision.yml file to confirm that your configuration has been loaded correctly and to identify any parsing errors or misconfigurations.

Performing Test Runs

The following terminal commands will perform a single run for the specified model type:

photoprism vision run -m labels --count 1 --force
photoprism vision run -m caption --count 1 --force

If output is empty, enable trace logging temporarily (PHOTOPRISM_LOG_LEVEL=trace) and re-run the command to inspect the request/response.