Use image endpoints

Generate one image first

Choose an available image model from the current catalog. This minimal request asks for one base64-encoded result and saves the JSON response:

export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/generations \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A clean product banner on a neutral background",
    "response_format": "b64_json",
    "n": 1
  }' \
  -o response.json

A representative response has a data array. Each item contains either b64_json or url, according to the requested and supported response format:

{
  "created": 1786651200,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

For the b64_json request above, decode the first result into a file:

node -e 'const fs = require("node:fs"); const body = JSON.parse(fs.readFileSync("response.json", "utf8")); fs.writeFileSync("image.png", Buffer.from(body.data[0].b64_json, "base64"));'

If you request url and the selected model supports it, read data[0].url instead. A successful response is never an empty generation: it contains at least one usable image item.

Start with generation, then add only options published by the selected model.

Discover capabilities before adding options

The image-specific catalog exposes current models, availability, operations, option constraints, reference limits, and streaming support, meaning whether partial results can arrive before the final images:

export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/models \
  -H "Authorization: Bearer $PROVOD_API_KEY"

Check the selected record's available, capabilities, and supported_parameters. Options such as aspect_ratio, size, quality, resolution, background, output format, and compression are model-specific. For current Google image models, for example, aspect_ratio and resolution are separate controls whose allowed values come from that exact catalog record. Do not copy a combination from another model.

The field n controls the number of final output images, within the selected model's published range. It does not control edit references. Repeated image[] parts are ordered input images; their allowed count comes from capabilities.maxReferenceImages.

Stream through the unified endpoint

Streaming uses POST /v1/images, not /v1/images/generations. Select a currently available generation model whose catalog record permits at least one partial image, then make the request:

set -euo pipefail

export PROVOD_API_KEY="sk_..."

if ! IMAGE_MODELS_JSON="$(
  curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/models \
    -H "Authorization: Bearer $PROVOD_API_KEY"
)"; then
  printf '%s\n' "$IMAGE_MODELS_JSON" >&2
  exit 1
fi

if ! PROVOD_IMAGE_MODEL="$(
  jq -er '
    first(
      .data[]
      | select(
          .available == true
          and .capabilities.generation == true
          and .supports_streaming == true
          and ((.supported_parameters.partial_images.max // 0) >= 1)
        )
      | .id
    )
  ' <<<"$IMAGE_MODELS_JSON"
)"; then
  printf 'No available streaming image model found in /v1/images/models.\n' >&2
  exit 1
fi

export PROVOD_IMAGE_MODEL

jq -n --arg model "$PROVOD_IMAGE_MODEL" '{
  model: $model,
  prompt: "A clean product banner on a neutral background",
  stream: true,
  partial_images: 1,
  n: 1
}' | curl --no-buffer --fail-with-body --silent --show-error https://api.provod.ai/v1/images \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

Each SSE record uses a data: line. Read the JSON type field to distinguish partial, completed, and error records. A successful stream can contain partial and completed image records and ends with [DONE]:

data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"iVBORw0KGgo..."}

data: {"type":"image_generation.completed","b64_json":"iVBORw0KGgo..."}

data: [DONE]

A failed stream can emit a data record with the public code and message:

data: {"type":"error","error":{"code":"IMAGE_UPSTREAM_FAILED","message":"Image generation failed"}}

Treat type: error or a connection close before [DONE] as incomplete. Retry with a bounded backoff only if no partial or completed image has arrived. After output starts, preserve it and require an explicit decision before another request because an automatic retry can duplicate work and cost.

Edit with multipart form data

Use POST /v1/images/edits only for a model whose catalog record publishes edit support. curl -F creates the required multipart/form-data body and boundary:

export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/edits \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -F "model=google/gemini-3.1-flash-image" \
  -F "prompt=Keep the subject and replace the background" \
  -F "image[]=@reference.png" \
  -F "aspect_ratio=16:9" \
  -F "response_format=b64_json" \
  -o response.json

Add more image[] parts in the intended order only while staying within the model's current reference limit. Add a mask part only when the model publishes mask support.

A public error code is the client-facing code in an API error response. MODEL_PARAMETER_COMBINATION_INVALID means the selected model cannot accept the requested option combination. MODEL_CAPABILITY_METADATA_UNAVAILABLE means the service cannot currently verify that combination against capability metadata. Use the exact returned code and current catalog values instead of guessing a replacement option.

Troubleshooting