Quickstart

From nothing to an edited picture: install Obraz, run it on your machine, edit in the browser, edit from a script, then let a model remove a background. Editing needs nothing but Obraz; the model steps need an image model service, which is Brama in a Wisent deployment or the OpenAI API anywhere else.

1. Install

On a machine with Stado, install the CLI from the canonical checkout:

stado product install obraz --surface cli

Without Stado, with access to the repository and a Rust toolchain (rustup.rs):

cargo install --git https://github.com/wisent-ai/obraz obraz
obraz version

2. Run Obraz on your machine

The service needs one value of its own: the secret every caller sends. Make one, keep it in a file only you can read, and start the service on a loopback port the system chooses:

umask 077
openssl rand -hex 32 > ~/.obraz-secret
OBRAZ_SECRET="$(cat ~/.obraz-secret)" obraz serve --port 0

Its first line, obraz listening on <address>, is the address the rest of this page calls $URL. This Obraz edits pictures; it has no renderer and no image model service, and GET /readyz says so, naming the variables that would give it each (configuration).

3. Edit in the browser

Open that address. Paste the secret, add a photo, and pick an example to start from:

• Instagram post 4:5 — crop to the post's ratio, size it to 1080 × 1350, lift contrast and colour, add a vignette.
• Story 9:16 on a blurred backdrop — the whole photo centred on a tall frame filled with a blurred copy of itself.
• Round avatar — a centred square, sized and cut to a circle with a transparent outside.
• Hide a face — a mosaic over one region; change the region to where the face is.
• Logo watermark — add your logo as the second picture and lay it in a corner.
• Two-picture collage — two photos side by side on white.

Press Edit. The picture appears with its size after every step and a download link; a refusal shows its status, the step and the reason.

4. Edit from a script

The editor sends what any program can. This turns photo.jpg into a round, framed avatar:

URL="<the address obraz serve printed>"
jq -n --arg photo "$(base64 < photo.jpg | tr -d '\n')" '{
  plan: {steps: [
    {op: "crop_ratio", ratio: "1:1", anchor: "center"},
    {op: "resize", width: 512, height: 512, fit: "cover", filter: "lanczos3"},
    {op: "border", width: 12, color: "#ffffff"},
    {op: "mask", shape: "ellipse"}]},
  inputs: [$photo],
  output: {format: "png"}}' \
| curl -s "$URL/v1/edits" -H "x-obraz-secret: $(cat ~/.obraz-secret)" \
       -H 'content-type: application/json' --data-binary @- \
| jq -r .image_base64 | base64 --decode > avatar.png

More plans worth trying, each a list of steps from Editing pictures:

• A product grid: collage of four shots with a white gap, then text with your font asset for the price.
• A colour grade for a whole shoot: the same lut step with your .cube table on every photo.
• A redacted screenshot: pixelate over each name, then border.
• A thumbnail: crop_ratio 16:9, adjust exposure and saturation, text with a stroke and a shadow.

5. Add the model steps

Background removal, object erasing, expanding the frame and the other model steps go to an image model service. Give Obraz its address, a file with its bearer and the model to ask, and start it again.

With the OpenAI API:

umask 077
printf '%s' "$OPENAI_API_KEY" > ~/.obraz-openai-key
OBRAZ_SECRET="$(cat ~/.obraz-secret)" \
OBRAZ_IMAGE_MODEL_URL=https://api.openai.com \
OBRAZ_IMAGE_MODEL_TOKEN_FILE=~/.obraz-openai-key \
OBRAZ_IMAGE_MODEL=gpt-image-1 \
obraz serve --port 0

In a Wisent deployment the release manifest grants Obraz call:brama#image-model, Stado delivers the bearer, and the deployment names Brama's address and OBRAZ_IMAGE_MODEL=image-model (configuration).

Then pick Product photo on white in the editor: the model removes the background and Obraz puts the product on a white square. Every model step is a billed call to the provider.