Models

Discover runnable image and video models, capabilities, parameter schemas, and duration estimates.

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

Operations

Operation	Purpose	Scopes
`GET /models`	List runnable image and video models	image:generate?, video:generate?
`GET /models/{modelKey}`	Read an image or video model schema	image:generate?, video:generate?

`GET /models`

List runnable image and video models

Returns models Gavana can invoke through the managed runtime or the actor’s saved connections.

Operation id: listModels
Scopes: Requires at least one of image:generate or video:generate.
CLI equivalent: gavana model list

Parameters

Parameter	In	Type	Required	Notes
`q`	query	string	No	Free-text model, provider, connection, or capability search. max length 240.
`provider`	query	string	No	max length 80.
`capability`	query	string	No	One of `image.generate`, `image.edit`, `image.variations`, `video.generate`, `video.generate.fromImage`, `video.generate.fromFrames`, `video.generate.fromReferences`.
`limit`	query	integer	No	Maximum number of items in this page. min 1, max 100.
`cursor`	query	string	No	Opaque continuation cursor from page.nextCursor. Reuse it with the same list filters. max length 8192.

Responses

Status	Payload	Meaning
`200`	object	Runnable image and video models with typed schemas and pagination.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`models`	array of ImageModel	Yes	—
`models[].id`	string	Yes	Pattern `^[A-Za-z0-9_-]{8,600}$`.
`models[].handle`	string	Yes	Pattern `^model:[A-Za-z0-9_-]{8,600}$`.
`models[].modelId`	string	Yes	min length 1, max length 240.
`models[].name`	string	Yes	—
`models[].provider`	string	Yes	One of `craftboard`, `openai`, `google/nano-banana`, `black-forest-labs`, `recraft`, `ideogram`, `qwen`, `openrouter`.
`models[].providerLabel`	string	Yes	—
`models[].connectionId`	string \| null	Yes	—
`models[].connectionName`	string	Yes	—
`models[].type`	string	Yes	One of `image`, `video`.
`models[].capabilities`	array of ImageModelCapability	Yes	min items 1.
`models[].parameters`	array of ImageModelParameter	Yes	—
`models[].parameters[].name`	string	Yes	—
`models[].parameters[].label`	string	Yes	—
`models[].parameters[].description`	string	Yes	—
`models[].parameters[].type`	string	Yes	One of `string`, `integer`, `number`, `boolean`, `string[]`, `image[]`.
`models[].parameters[].required`	boolean	Yes	—
`models[].parameters[].min`	number	No	—
`models[].parameters[].max`	number	No	—
`models[].parameters[].options`	array of object	No	—
`models[].parameters[].options[].label`	string	Yes	—
`models[].parameters[].options[].value`	string	Yes	—
`models[].parameters[].options[].description`	string	No	—
`models[].parameters[].capabilities`	array of ImageModelCapability	Yes	—
`models[].estimatedSeconds`	integer	Yes	min 1.
`models[].beta`	boolean	Yes	—
`page`	CursorPage	Yes	—
`page.limit`	integer	Yes	min 1, max 200.
`page.hasMore`	boolean	Yes	—
`page.nextCursor`	string \| null	Yes	max length 8192.

Example


curl "https://app.gavana.ai/api/canvas-agent/v1/models" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN"

`GET /models/{modelKey}`

Read an image or video model schema

Operation id: getModel
Scopes: Requires at least one of image:generate or video:generate.
CLI equivalent: gavana model get

Parameters

Parameter	In	Type	Required	Notes
`modelKey`	path	string	Yes	Opaque key from a model:<key> handle. Pattern `^[A-Za-z0-9_-]{8,600}$`.

Responses

Status	Payload	Meaning
`200`	object	One runnable image or video model with its connection-specific schema.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`model`	ImageModel	Yes	—
`model.id`	string	Yes	Pattern `^[A-Za-z0-9_-]{8,600}$`.
`model.handle`	string	Yes	Pattern `^model:[A-Za-z0-9_-]{8,600}$`.
`model.modelId`	string	Yes	min length 1, max length 240.
`model.name`	string	Yes	—
`model.provider`	string	Yes	One of `craftboard`, `openai`, `google/nano-banana`, `black-forest-labs`, `recraft`, `ideogram`, `qwen`, `openrouter`.
`model.providerLabel`	string	Yes	—
`model.connectionId`	string \| null	Yes	—
`model.connectionName`	string	Yes	—
`model.type`	string	Yes	One of `image`, `video`.
`model.capabilities`	array of ImageModelCapability	Yes	min items 1.
`model.parameters`	array of ImageModelParameter	Yes	—
`model.parameters[].name`	string	Yes	—
`model.parameters[].label`	string	Yes	—
`model.parameters[].description`	string	Yes	—
`model.parameters[].type`	string	Yes	One of `string`, `integer`, `number`, `boolean`, `string[]`, `image[]`.
`model.parameters[].required`	boolean	Yes	—
`model.parameters[].min`	number	No	—
`model.parameters[].max`	number	No	—
`model.parameters[].options`	array of object	No	—
`model.parameters[].options[].label`	string	Yes	—
`model.parameters[].options[].value`	string	Yes	—
`model.parameters[].options[].description`	string	No	—
`model.parameters[].capabilities`	array of ImageModelCapability	Yes	—
`model.estimatedSeconds`	integer	Yes	min 1.
`model.beta`	boolean	Yes	—

Example


curl "https://app.gavana.ai/api/canvas-agent/v1/models/seedream-4-0-250828" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN"

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.