Images

POST /v1/media/images renders synchronously: the reply carries the finished files and what the render cost. There is no job to poll — an image is done before the request returns, so it is never a media_job. The same render is what an agent’s generate_image tool does; the catalogue is shared. Images are not model calls: the image catalogue is its own, and an image model is never an agent’s model.

The image generation object

string

Always image_generation.

string

The model that rendered, which is the one you named or the default it picked.

File[]

One file per rendered image, n of them when the model produced that many. Each is published and carries source.type = image_generation.

integer

What was debited for the render, in integer micro-USD, on the media tier. See Pricing.

Generate images

POST /v1/media/images → 200 OK — scope agents:write, Idempotency-Key required.

string

required

What to render.

string

A model id from GET /v1/media/models?kind=image. Omitted, the cheapest priced image model is used; an id the catalogue does not know is validation_failed.

string[]

Up to 4 public http(s) reference images for an edit or an image-to-image render. A private or loopback host is validation_failed.

integer

How many images, 1–4. Default 1. Every one is filed — none is dropped.

string

Such as 16:9 or 1:1. Passed to the model as-is; a model that does not take one ignores it.

integer

Repeat an earlier result, on models that honour a seed.

That is the whole request. Each output is filed in the format the model returned it — PNG unless the model says otherwise — and content_type on the file says which. Not on the request today: an explicit size or resolution, quality, output_format, a transparent background, more than 4 references or 4 outputs, and any per-model or per-provider passthrough. A body that carries one of them is validation_failed, not quietly dropped; ask for the field if you need it.

curl -fsSL https://api.vetta.sh/v1/media/images \
  -H "authorization: Bearer sk_live_..." \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{ "prompt": "a paper kite over a grey harbour", "n": 2, "aspect_ratio": "16:9" }'

const out = await client.media.images.generate({
  prompt: "a paper kite over a grey harbour",
  n: 2,
  aspect_ratio: "16:9",
});
for (const file of out.files) console.log(file.id, file.content_type);

vetta media generate --kind image --prompt "a paper kite over a grey harbour" --n 2 --aspect-ratio 16:9

{
  "object": "image_generation",
  "model": "example/thrifty-image",
  "files": [
    {
      "id": "fil_01J...",
      "object": "file",
      "name": "image-fil_01J....png",
      "content_type": "image/png",
      "size_bytes": 184201,
      "scope": "published",
      "session_id": null,
      "sha256": "…",
      "created_at": "2026-09-06T12:00:00.000Z"
    }
  ],
  "cost_micro_usd": 50340
}

Read the bytes with GET /v1/files/{id}?download=true.

Billing

A render is billed what it actually cost, once it has happened, on the media tier; nothing is quoted or held beforehand, because the catalogue publishes no price for most models and a picture costs cents. There is no balance check before the render: a low balance goes negative by the cost of the image rather than turning the request away. The debit settles under the request’s idempotency key, so a replayed request returns the same files and charges once. A render the model refuses or fails is provider_error and is not billed.

In a session

An agent renders with the generate_image tool — the same route, the same catalogue, the same fields (prompt, model?, image_urls?, n?, aspect_ratio?, seed?) — and gets the file_ids back in the same turn, because the render is synchronous. Two differences from calling the route yourself:

The model default is yours to set. tools.configs.generate_image.config.models on the agent names the model that runs when the agent does not choose one; with none pinned, the cheapest priced image model is used, as here. It is a default, not an allow-list — the agent may still name any id the catalogue publishes.
The bill lands on the agent. The debit carries the session_id and settles against the agent’s budget as the media component; a render through this route carries no session and settles against the organization.

Errors

Code	When
`validation_failed`	Missing `Idempotency-Key`, an unknown `model`, a private-host `image_urls` entry, `n` outside 1–4, a field the request does not carry.
`provider_error`	The model failed or refused; nothing is filed and nothing is billed.
`feature_not_configured`	This deploy has no generation provider configured.

Stock photos

GET /v1/media/stock — scope agents:read Searches a stock photo library and returns up to count photos, each with a direct image URL at the size you asked for, a small preview, and the photographer credit the licence asks you to show. Free: a search is booked to the ledger as a search line at $0, so it shows up in a spend breakdown as a call that happened, not as one that was never priced.

string

required

What the photo should show. 1–200 characters.

number

default:"10"

How many photos to return, 1–30. There is no cursor: count is the whole page.

string

landscape, portrait or square.

string

A dominant colour — a name such as red, blue, brown, black, white, or a hex value such as #978E82.

string

The image size url points at: small, medium or large. Default large. Picks the rendition only — it does not narrow the results.

curl -fsSL "https://api.vetta.sh/v1/media/stock?query=office+workspace&count=3&orientation=landscape" \
  -H "authorization: Bearer sk_live_..."

const { data } = await client.media.stock.search({ query: "office workspace", count: 3, orientation: "landscape" });

vetta media stock "office workspace" --count 3 --orientation landscape

{
  "data": [
    {
      "object": "stock_photo",
      "id": "2014422",
      "width": 3024,
      "height": 2016,
      "url": "https://images.example/2014422.jpeg?w=940",
      "preview_url": "https://images.example/2014422.jpeg?w=280",
      "alt": "Brown rocks during golden hour",
      "photographer": "Joey Farina",
      "attribution_url": "https://photos.example/photo/2014422/",
      "dominant_color": "#978E82"
    }
  ]
}

The stock photo object

string

Always stock_photo.

string

The library’s own id for the photo. Opaque and unprefixed — it is not a Vetta resource id and cannot be fetched on its own; keep the photo by importing its url as a file.

number

Pixel width of the original.

number

Pixel height of the original. width > height is a landscape photo.

string

A direct image URL at the requested size. Fetchable without a key.

string

A small thumbnail, for picking before downloading.

string | null

A one-line description of the photo, when the library has one.

string | null

Who took it. The licence asks that this credit be shown wherever the photo is used.

string | null

The page to link the credit to. This is the one field that may point at the library’s own domain.

string | null

The photo’s average colour as a hex value.

Keeping a photo

A result is a URL, not a file. To hold the bytes as a fil_ — so a session can attach it, or a page can serve it from your own storage — import url through Files; the imported file records where it came from as a URL import.

In a session

Agents reach the same search as the find_stock_photo tool, which takes query, count and orientation. It is on by default with permission allow.

Errors

Status	Code	When
`400`	`validation_failed`	`query` missing, `count` outside 1–30, or a filter value outside its set.
`429`	`rate_limited`	The library’s request allowance for this deploy is spent; retry shortly.
`501`	`feature_not_configured`	This deploy has no stock photo library configured.
`502`	`provider_error`	The library answered with an error.

Introduction

Core resources

Platform

Identity

The image generation object

Generate images

Billing

In a session

Errors

Stock photos

The stock photo object

Keeping a photo

In a session

Errors

​The image generation object

​Generate images

​Billing

​In a session

​Errors

​Stock photos

​The stock photo object

​Keeping a photo

​In a session

​Errors

The image generation object

Generate images

Billing

In a session

Errors

Stock photos

The stock photo object

Keeping a photo

In a session

Errors