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.

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.

integer

Repeat an earlier result.

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 beforehand because the catalogue publishes no price for most models. Before rendering, the organization’s prepaid balance is checked against a small floor — insufficient_credits if it is below it — and 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.

Errors

Code	When
`validation_failed`	Missing `Idempotency-Key`, an unknown `model`, a private-host `image_urls` entry, `n` outside 1–4.
`insufficient_credits`	The prepaid balance is below the admission floor.
`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

Errors

Stock photos

The stock photo object

Keeping a photo

In a session

Errors

​The image generation object

​Generate images

​Billing

​Errors

​Stock photos

​The stock photo object

​Keeping a photo

​In a session

​Errors

The image generation object

Generate images

Billing

Errors

Stock photos

The stock photo object

Keeping a photo

In a session

Errors