/ 
Langertha-0.503
/ langertha_image

NAME

langertha_image - Generate images through OpenAI or an explicit subscription proxy

VERSION

version 0.503

SYNOPSIS

langertha_image [options] PROMPT
langertha_image [options] --prompt-file FILE

# OpenAI Platform (LANGERTHA_OPENAI_API_KEY is exported)
langertha_image --backend openai --output "$HOME/cat.png" 'A cat at a loom'

# local subscription proxy, no API key
langertha_image --backend proxy --url http://127.0.0.1:18765/v1 \
  --prompt-file prompt.txt --output "$HOME/poster.png"

DESCRIPTION

Generates one to ten images through Langertha::Engine::OpenAI and stores them as files. The backend is always chosen explicitly: proxy for an OpenAI-compatible local subscription proxy, openai for the regular OpenAI Platform. There is no discovery, no auto mode and no fallback from one to the other.

OPTIONS

--backend proxy|openai

The route to use. Defaults to LANGERTHA_IMAGE_BACKEND, then openai.

--url URL

Base URL including /v1 for the chosen backend, for this call only. Must be http(s) and carry no credentials, query or fragment.

--prompt-file FILE

Read the prompt from FILE (UTF-8) instead of the positional argument. Give exactly one of PROMPT or --prompt-file.

--prompt-prefix TEXT

Text placed as its own paragraph before the prompt. Overrides LANGERTHA_IMAGE_PROMPT_PREFIX.

--output FILE

Target path. Without it the name is derived from the prompt and placed in $HOME (langertha-image-<slug>.png). The directory must exist. With --n above 1 the files get a -1, -2, ... suffix before the extension.

--model ID

Image model. Defaults to LANGERTHA_IMAGE_MODEL, then the engine default.

--size SIZE

Output size, e.g. 1024x1024. Defaults to LANGERTHA_IMAGE_SIZE.

--quality LEVEL

Quality level. Defaults to LANGERTHA_IMAGE_QUALITY.

--background MODE

Background mode, e.g. opaque. Defaults to LANGERTHA_IMAGE_BACKGROUND.

--n COUNT

Number of images, 1 to 10. Defaults to LANGERTHA_IMAGE_N, then 1.

--force

Replace existing target files. Without it an existing target (or dangling symlink) is an error raised before any request is sent.

--help

Print this help.

An API key is never accepted as an option, so it cannot land in process lists or shell history.

ENVIRONMENT

LANGERTHA_IMAGE_BACKEND

Default for --backend.

LANGERTHA_IMAGE_PROXY_URL

Base URL for the proxy backend. Never read by openai.

LANGERTHA_IMAGE_OPENAI_URL

Base URL for the openai backend. Never read by proxy.

LANGERTHA_IMAGE_PROMPT_PREFIX

Default for --prompt-prefix.

LANGERTHA_IMAGE_MODEL, LANGERTHA_IMAGE_SIZE, LANGERTHA_IMAGE_QUALITY, LANGERTHA_IMAGE_BACKGROUND, LANGERTHA_IMAGE_N

Defaults for the matching options.

LANGERTHA_OPENAI_API_KEY

API key of the openai backend (Langertha's regular resolution). The proxy backend sends no key and no Authorization header.

OUTPUT

stdout carries only the finished file paths, one per line. stderr carries the backend, model, token usage and runtime. Base64 payloads and signed image URLs (query, credentials) are never printed.

BILLING BOUNDARY

proxy talks only to the URL you gave it and uses no API key: it is the subscription route. openai uses the OpenAI Platform key and is billed separately. A failed proxy call never falls back to openai.

ERRORS

The exit status is 0 on success and non-zero otherwise. Invalid options, a missing proxy URL, an existing target and a missing output directory fail before any request. An empty, malformed or wrong-sized provider answer, invalid Base64 or a failed download creates no file; temporary files are removed. If image N of several fails, the images finished before it stay and are listed on stderr as already finalized: PATH.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.