Videos

Queue video generation from prompts, first and last frames, or reference images.

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

Operations

Operation	Purpose	Scopes
`POST /videos/generate`	Queue video generation	canvas:read, asset:read, video:generate

`POST /videos/generate`

Queue video generation

Starts a retry-safe video job using a connected video model. First, last, and reference frames may be stable image node or asset handles, or public HTTPS image URLs.

Operation id: startVideoGeneration
Scopes: Requires canvas:read + asset:read + video:generate.
CLI equivalent: gavana video generate

Request body (application/json, required)

Field	Type	Required	Notes
`model`	string	Yes	A provider model id or opaque model:<key> handle from GET /models?capability=video.generate. min length 1, max length 650.
`connectionId`	string	No	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`prompt`	string	Yes	min length 1, max length 8000.
`idempotencyKey`	string	Yes	A stable retry key. Reusing it with the same request returns the original job; reusing it with different inputs returns 409. min length 8, max length 200.
`canvasId`	string	No	Required when a frame or reference is a node: handle. Accepts a plain id, canvas:<id>, or canvas:<ownerUid>:<id>.
`ownerUid`	string	No	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`aspectRatio`	string	No	max length 80.
`durationSeconds`	integer	No	min 1, max 120.
`resolution`	string	No	max length 80.
`generateAudio`	boolean	No	—
`firstFrame`	string	No	A stable image node or asset handle, or a public HTTPS image URL. max length 2048. Pattern `^(?:node:[A-Za-z0-9_-]{1,180}\|asset:(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180}\|https://.+)$`.
`lastFrame`	string	No	A stable image node or asset handle, or a public HTTPS image URL. max length 2048. Pattern `^(?:node:[A-Za-z0-9_-]{1,180}\|asset:(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180}\|https://.+)$`.
`references`	array of VideoFrameReference	No	max items 9.

Validation rules the service enforces across these fields:

lastFrame requires firstFrame
node: frame references require canvasId
connectionId must match the selected model handle when both are supplied

Responses

Status	Payload	Meaning
`202`	ImageJob \| VideoJob	An image, Action, or video job state or finalized result. Image and Action results follow the documented Run retention policy. Video records are retained for 30 days and expose a protected download URL after completion.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

202 response body

Field	Type	Required	Notes
`(ImageJob).id`	string	Yes	Pattern `^job:`.
`(ImageJob).run`	string	Yes	Pattern `^run:`.
`(ImageJob).kind`	string	Yes	One of `image`, `action`.
`(ImageJob).pollUrl`	string	Yes	Pattern `^/api/canvas-agent/v1/runs/`.
`(ImageJob).rawId`	string (uuid)	No	—
`(ImageJob).status`	string	Yes	Current temporary job state. Successful results retain the 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. Expired tombstones remain seven days. One of `preparing`, `queued`, `running`, `finalizing`, `canceling`, `succeeded`, `failed`, `canceled`, `expired`.
`(ImageJob).estimatedSeconds`	integer	No	Typical provider runtime for the selected model. This is guidance, not a deadline. min 1.
`(ImageJob).durationMs`	integer	No	Total observed duration once the job is terminal. min 0.
`(ImageJob).timing`	ImageJobTiming	No	—
`(ImageJob).timing.createdAt`	string (date-time)	No	—
`(ImageJob).timing.queuedAt`	string (date-time)	No	—
`(ImageJob).timing.startedAt`	string (date-time)	No	—
`(ImageJob).timing.completedAt`	string (date-time)	No	—
`(ImageJob).timing.queueDurationMs`	integer	No	min 0.
`(ImageJob).timing.executionDurationMs`	integer	No	min 0.
`(ImageJob).timing.totalDurationMs`	integer	No	min 0.
`(ImageJob).failure`	ImageJobFailure	No	—
`(ImageJob).failure.code`	string	Yes	One of `provider_authentication_failed`, `provider_timeout`, `provider_rate_limited`, `provider_rejected`, `provider_unavailable`, `runtime_failed`, `action_input_invalid`, `result_expired`.
`(ImageJob).failure.message`	string	Yes	—
`(ImageJob).failure.retryable`	boolean	Yes	—
`(ImageJob).failure.providerStatus`	integer	No	min 400, max 599.
`(ImageJob).webhook`	ImageJobWebhookDelivery	No	Durable delivery state. Gavana makes 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.
`(ImageJob).webhook.id`	string	Yes	Pattern `^webhook:`.
`(ImageJob).webhook.status`	string	Yes	One of `pending`, `delivering`, `delivered`, `failed`.
`(ImageJob).webhook.attempts`	integer	Yes	min 0.
`(ImageJob).webhook.nextAttemptAt`	string (date-time)	No	—
`(ImageJob).webhook.lastAttemptAt`	string (date-time)	No	—
`(ImageJob).webhook.deliveredAt`	string (date-time)	No	—
`(ImageJob).webhook.lastStatus`	integer	No	min 100, max 599.
`(ImageJob).webhook.errorCode`	string	No	One of `invalid_destination`, `delivery_failed`, `redirect_not_allowed`, `endpoint_rejected`, `secret_unavailable`, `finalization_unavailable`, `finalization_auth_unavailable`, `finalization_auth_expired`, `finalization_failed`.
`(ImageJob).replayed`	boolean	No	—
`(ImageJob).operation`	string	No	One of `generate`, `edit`, `variations`, `action`.
`(ImageJob).actionId`	string	No	Pattern `^action:`.
`(ImageJob).actionVersion`	string	No	—
`(ImageJob).canvasId`	string	No	Pattern `^canvas:`.
`(ImageJob).canvasRevision`	string	No	—
`(ImageJob).canvasUrl`	string (uri)	No	—
`(ImageJob).canceledAt`	string (date-time)	No	—
`(ImageJob).cancelReason`	string	No	One of `stale_preparing`, `user_requested`, `setup_failed`.
`(ImageJob).targets`	array of string	No	—
`(ImageJob).references`	array of string	No	—
`(ImageJob).referenceInputs`	array of ImageReferenceInput	No	Exact reference handles and optional semantic roles used by the provider request.
`(ImageJob).referenceInputs[].handle`	string	Yes	Pattern `^(?:node:[A-Za-z0-9_-]{1,180}\|asset:(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180})$`.
`(ImageJob).referenceInputs[].role`	string	No	One of `identity`, `construction`, `texture`, `fit`, `style`.
`(ImageJob).images`	array of ImageJobResultImage	No	—
`(ImageJob).images[].assetId`	string	Yes	Pattern `^asset:`.
`(ImageJob).images[].nodeId`	string	Yes	Pattern `^node:`.
`(ImageJob).images[].mediaType`	string	No	Pattern `^image/`.
`(ImageJob).images[].width`	integer	No	min 1.
`(ImageJob).images[].height`	integer	No	min 1.
`(ImageJob).images[].bytes`	integer	No	min 1.
`(ImageJob).images[].previewUrl`	string (uri)	Yes	—
`(ImageJob).images[].markdown`	string	No	—
`(ImageJob).completionReview`	CanvasCompletionReview	No	—
`(ImageJob).completionReview.status`	string	Yes	One of `ready`, `needs-review`, `blocked`.
`(ImageJob).completionReview.doneClaimAllowed`	boolean	Yes	False while agent-owned spatial or lineage findings remain, or a generated output is pending, failed, or non-durable.
`(ImageJob).completionReview.instruction`	string	Yes	—
`(ImageJob).completionReview.outputs`	CanvasCompletionOutputs	Yes	Generated-output count and durable, pending, and failed breakdown.
`(ImageJob).completionReview.outputs.count`	integer	Yes	min 0.
`(ImageJob).completionReview.outputs.durableCount`	integer	Yes	min 0.
`(ImageJob).completionReview.outputs.pendingCount`	integer	Yes	min 0.
`(ImageJob).completionReview.outputs.failedCount`	integer	Yes	min 0.
`(ImageJob).completionReview.outputs.handles`	array of string	Yes	—
`(ImageJob).completionReview.overlap`	CanvasCompletionFindingArea	Yes	—
`(ImageJob).completionReview.overlap.status`	string	Yes	One of `clear`, `needs-review`, `blocked`.
`(ImageJob).completionReview.overlap.findingCodes`	array of string	Yes	—
`(ImageJob).completionReview.overlap.nodeHandles`	array of string	Yes	—
`(ImageJob).completionReview.overlap.connectionHandles`	array of string	Yes	—
`(ImageJob).completionReview.containment`	CanvasCompletionFindingArea	Yes	—
`(ImageJob).completionReview.containment.status`	string	Yes	One of `clear`, `needs-review`, `blocked`.
`(ImageJob).completionReview.containment.findingCodes`	array of string	Yes	—
`(ImageJob).completionReview.containment.nodeHandles`	array of string	Yes	—
`(ImageJob).completionReview.containment.connectionHandles`	array of string	Yes	—
`(ImageJob).completionReview.referenceLineage`	CanvasCompletionFindingArea	Yes	—
`(ImageJob).completionReview.referenceLineage.status`	string	Yes	One of `clear`, `needs-review`, `blocked`.
`(ImageJob).completionReview.referenceLineage.findingCodes`	array of string	Yes	—
`(ImageJob).completionReview.referenceLineage.nodeHandles`	array of string	Yes	—
`(ImageJob).completionReview.referenceLineage.connectionHandles`	array of string	Yes	—
`(ImageJob).completionReview.productFidelity`	CanvasProductFidelityReview	Yes	A conservative review signal, not an authoritative visual inspection.
`(ImageJob).completionReview.productFidelity.status`	string	Yes	One of `not-applicable`, `needs-review`, `passed`.
`(ImageJob).completionReview.productFidelity.reviewedOutputCount`	integer	Yes	min 0.
`(ImageJob).completionReview.productFidelity.needsReviewOutputHandles`	array of string	Yes	—
`(ImageJob).completionReview.productFidelity.evidenceMissingOutputHandles`	array of string	Yes	—
`(ImageJob).completionReview.productFidelity.reasons`	array of object	No	—
`(ImageJob).completionReview.productFidelity.reasons[].nodeHandle`	string	Yes	Pattern `^node:`.
`(ImageJob).completionReview.productFidelity.reasons[].reason`	string	Yes	—
`(ImageJob).completionReview.delivery`	CanvasCompletionDelivery	Yes	Generated-output delivery evidence. A blocked state prevents a Done claim.
`(ImageJob).completionReview.delivery.status`	string	Yes	One of `clear`, `blocked`.
`(ImageJob).completionReview.delivery.reasons`	array of string	No	—
`(ImageJob).completionReview.delivery.pendingOutputHandles`	array of string	Yes	—
`(ImageJob).completionReview.delivery.failedOutputHandles`	array of string	Yes	—
`(ImageJob).completionReview.delivery.nonDurableOutputHandles`	array of string	Yes	—
`(ImageJob).completionReview.blockingFindingCodes`	array of string	Yes	—
`(ImageJob).completionReview.advisoryFindingCodes`	array of string	Yes	—
`(VideoJob).id`	string	Yes	Pattern `^job:`.
`(VideoJob).rawId`	string (uuid)	Yes	—
`(VideoJob).kind`	“video”	Yes	—
`(VideoJob).operation`	“generate”	Yes	—
`(VideoJob).pollUrl`	string	Yes	Pattern `^/api/canvas-agent/v1/jobs/`.
`(VideoJob).status`	string	Yes	One of `queued`, `running`, `succeeded`, `failed`, `canceled`.
`(VideoJob).model`	object	Yes	—
`(VideoJob).model.id`	string	Yes	—
`(VideoJob).model.name`	string	Yes	—
`(VideoJob).progress`	number	Yes	min 0, max 100.
`(VideoJob).estimatedSeconds`	integer	Yes	min 1.
`(VideoJob).providerRunId`	string	No	—
`(VideoJob).failure`	VideoJobFailure	No	—
`(VideoJob).failure.code`	string	Yes	One of `video_generation_failed`, `canceled`.
`(VideoJob).failure.message`	string	Yes	—
`(VideoJob).failure.retryable`	boolean	Yes	—
`(VideoJob).video`	object	No	—
`(VideoJob).video.downloadUrl`	string	Yes	Pattern `^/api/canvas-agent/v1/jobs/.+/output$`.
`(VideoJob).replayed`	boolean	No	—
`(VideoJob).createdAt`	string (date-time)	Yes	—
`(VideoJob).updatedAt`	string (date-time)	Yes	—

Example


curl -X POST "https://app.gavana.ai/api/canvas-agent/v1/videos/generate" \
  -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.