Using the Canvora REST API

Canvora's REST API lets you generate visuals programmatically from your own applications. You can create generations, check status, retrieve outputs, and edit images — all with a simple API key.

Requirements

API keys are available on Pro and Business plans. Free and Starter users can upgrade at canvora.ai/subscription.

Creating an API Key

Go to canvora.ai/integrations and select the API Keys tab
Click Create New Key
Give it a name (e.g., "My App" or "Content Pipeline")
Copy the key immediately — it's only shown once

Your key starts with vd_ and looks like: vd_abc123def456...

Authentication

Include your API key in the X-API-Key header of every request:

X-API-Key: vd_your_api_key_here

Quick Start

Create a generation

curl -X POST https://api.canvora.ai/api/generations -H "X-API-Key: vd_YOUR_KEY" -H "Content-Type: application/json" -d '{"input_type":"text","input_content":"5 tips for remote work productivity","output_formats":["linkedin_carousel"],"carousel_slides":{"linkedin_carousel":5}}'

This returns a generation ID that you can poll for status.

Check generation status

curl https://api.canvora.ai/api/generations/GENERATION_ID -H "X-API-Key: vd_YOUR_KEY"

When status is "completed", the outputs array contains your image URLs.

List your brand kits

curl https://api.canvora.ai/api/brands -H "X-API-Key: vd_YOUR_KEY"

Check credit balance

curl https://api.canvora.ai/api/credits/balance -H "X-API-Key: vd_YOUR_KEY"

Available Endpoints

Method	Endpoint	Description
POST	`/api/generations`	Create a new generation
GET	`/api/generations`	List your generations
GET	`/api/generations/:id`	Get generation status and outputs
GET	`/api/brands`	List your brand kits
GET	`/api/credits/balance`	Check credit balance
GET	`/api/idea-mode/formats`	List all available formats
POST	`/api/images/:id/edit`	Edit a generated image

Generation Parameters

When creating a generation via POST /api/generations:

Parameter	Type	Required	Description
`input_type`	string	Yes	`"text"`, `"url"`, or `"pdf"`
`input_content`	string	For text	The text content to visualize
`input_url`	string	For URL	URL to extract content from
`output_formats`	string	Yes	Array of format IDs (e.g., `["instagram_post", "linkedin_carousel"]`)
`carousel_slides`	object	For carousels	Slide counts per format (e.g., `{"linkedin_carousel": 7}`)
`brand_id`	string	No	Brand kit ID to apply
`visual_style`	string	No	One of: modern, minimal, bold, elegant, playful, corporate, creative, dark

Image Editing

Editing is a two-step process:

Step 1: Send edit instruction

curl -X POST https://api.canvora.ai/api/images/GENERATION_ID/edit -H "X-API-Key: vd_YOUR_KEY" -H "Content-Type: application/json" -d '{"outputId":"OUTPUT_ID","prompt":"Change the background to dark blue"}'

This returns a preview with a refined instruction.

Step 2: Confirm and execute

curl -X POST https://api.canvora.ai/api/images/GENERATION_ID/edit -H "X-API-Key: vd_YOUR_KEY" -H "Content-Type: application/json" -d '{"outputId":"OUTPUT_ID","prompt":"Change the background to dark blue","confirmedInstruction":"Change the background color from white to a deep navy blue (#1a1a4e)"}'

Rate Limits

Operation	Limit
Read endpoints (GET)	60 requests/minute
Generation (POST)	20 requests/minute
Default	30 requests/minute

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Responses

All errors follow this format:

{
  "error": "Error Type",
  "message": "Human-readable description",
  "code": "ERROR_CODE"
}

Common error codes:

Status	Meaning
401	Invalid or missing API key
403	Insufficient permissions or account deactivated
429	Rate limit exceeded
402	Insufficient credits

Security Best Practices

Never expose your API key in client-side code or public repositories
Use environment variables to store keys
Rotate keys periodically from the API Access page
Revoke any key immediately if it may have been compromised

On this page