Images

Queue image generation, editing, and variation jobs.

Base URL: https://app.gavana.ai/api/canvas-agent/v1 · Authentication: HTTP bearer, token format cba_<token-id>.<secret>

Operations

POST /images/edit

Queue an image edit

• Operation id: startImageEdit
• Scopes: Requires canvas:read + canvas:write + asset:read + image:generate. When elements contains at least one version-pinned Element, also requires element:read.
• CLI equivalent: gavana image edit

Request body (application/json, required)

At least one of references or source is required.

Validation rules the service enforces across these fields:

• references and source contain at most 16 handles combined
• references and source are unique when combined
• role-bearing references retain their exact handle and role in job and canvas provenance
• count equals the selected target count

Responses

202 response body

Callbacks

• imageJobTerminal → {$request.body#/webhook/url}: Receive a signed terminal image-job event. Gavana signs ${timestamp}.${rawBody} with HMAC-SHA256 and the caller-owned secret. Return any 2xx response to acknowledge delivery. Delivery uses four total attempts. Retryable network failures and 408, 425, 429, or 5xx responses back off for 10 seconds, 60 seconds, then 5 minutes; redirects and other 4xx responses stop delivery. Successful Image and Action callbacks already contain durable asset and node handles in data.run.images, so callback-only clients do not need a follow-up GET. A caller with job:manage may read the shared Run later for inspection. Successful image and Action results retain their temporary observation record for 24 hours before the first successful server finalization and 15 minutes after it; an authenticated Run GET or pre-callback worker finalization both count. Failed and canceled records keep the normal 24-hour window.

Example

curl -X POST "https://app.gavana.ai/api/canvas-agent/v1/images/edit" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /images/generate

Queue image generation

• Operation id: startImageGeneration
• Scopes: Requires canvas:read + canvas:write + asset:read + image:generate. When elements contains at least one version-pinned Element, also requires element:read.
• CLI equivalent: gavana image generate

Request body (application/json, required)

Validation rules the service enforces across these fields:

• references and source contain at most 16 handles combined
• references and source are unique when combined
• role-bearing references retain their exact handle and role in job and canvas provenance
• count equals the selected target count

Responses

202 response body

Callbacks

• imageJobTerminal → {$request.body#/webhook/url}: Receive a signed terminal image-job event. Gavana signs ${timestamp}.${rawBody} with HMAC-SHA256 and the caller-owned secret. Return any 2xx response to acknowledge delivery. Delivery uses four total attempts. Retryable network failures and 408, 425, 429, or 5xx responses back off for 10 seconds, 60 seconds, then 5 minutes; redirects and other 4xx responses stop delivery. Successful Image and Action callbacks already contain durable asset and node handles in data.run.images, so callback-only clients do not need a follow-up GET. A caller with job:manage may read the shared Run later for inspection. Successful image and Action results retain their temporary observation record for 24 hours before the first successful server finalization and 15 minutes after it; an authenticated Run GET or pre-callback worker finalization both count. Failed and canceled records keep the normal 24-hour window.

Example

curl -X POST "https://app.gavana.ai/api/canvas-agent/v1/images/generate" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /images/import

Import a public HTTPS image as a durable canvas node

Downloads a bounded raster image through Gavana’s SSRF-safe fetcher, stores it as a canvas-scoped asset, and adds one deterministic image node. Reuse the idempotency key only for the exact same import.

• Operation id: importImageToCanvas
• Scopes: Requires canvas:read + canvas:write + asset:read + image:generate.

Request body (application/json, required)

Responses

200 response body

Example

curl -X POST "https://app.gavana.ai/api/canvas-agent/v1/images/import" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "canvasId": "canvas:8f2c1d40-9a77-4c2e-9c11-2b0a5f6d7e31",
    "imageUrl": "https://example.com/gavana-webhook",
    "idempotencyKey": "2026-08-04-first-attempt"
  }'

POST /images/variations

Queue image variations

• Operation id: startImageVariations
• Scopes: Requires canvas:read + canvas:write + asset:read + image:generate. When elements contains at least one version-pinned Element, also requires element:read.
• CLI equivalent: gavana image variations

Request body (application/json, required)

At least one of references or source is required.

Validation rules the service enforces across these fields:

• references and source contain at most 16 handles combined
• references and source are unique when combined
• role-bearing references retain their exact handle and role in job and canvas provenance
• count equals the selected target count

Responses

202 response body

Callbacks

• imageJobTerminal → {$request.body#/webhook/url}: Receive a signed terminal image-job event. Gavana signs ${timestamp}.${rawBody} with HMAC-SHA256 and the caller-owned secret. Return any 2xx response to acknowledge delivery. Delivery uses four total attempts. Retryable network failures and 408, 425, 429, or 5xx responses back off for 10 seconds, 60 seconds, then 5 minutes; redirects and other 4xx responses stop delivery. Successful Image and Action callbacks already contain durable asset and node handles in data.run.images, so callback-only clients do not need a follow-up GET. A caller with job:manage may read the shared Run later for inspection. Successful image and Action results retain their temporary observation record for 24 hours before the first successful server finalization and 15 minutes after it; an authenticated Run GET or pre-callback worker finalization both count. Failed and canceled records keep the normal 24-hour window.

Example

curl -X POST "https://app.gavana.ai/api/canvas-agent/v1/images/variations" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors

Every failure uses the shared error envelope described in Errors and X-Request-ID. The response always carries X-Request-ID; share that value with support instead of the request payload.