Connect API: Image Generation now available in Preview

Announcements
, ,
1

Hello everyone!

You can now generate images with the Connect API. This is available in preview.

What’s new

Two new endpoints:

  • Create image generation job: POST /v1/image-generations
  • Get image generation job: GET /v1/image-generations/{jobId}

Generation takes a little while, so it follows the same async job pattern as exports and autofill: create the job, poll until it’s done, get a link to the image. The download URL is valid for 24 hours.

How to use it

You need a user access token with the asset:write scope. The minimal request is a prompt and an idempotency key:

POST /v1/image-generations
{
  "prompt": "A watercolor painting of a lighthouse at sunrise",
  "aspect_ratio": "landscape",
  "idempotency_key": "4b8f6a2e-1c9d-4b7a-9f3e-2d5c8a7b6e01"
}

A few things you can do from there:

  • model is optional. If you don’t set it, we pick a model for the request. You can also pin lucid_origin or z_image_turbo. If a pinned model can’t serve the request the job fails — we never swap in a different model.
  • aspect_ratio can be square, landscape or portrait.
  • Set asset_upload to { "type": "upload" } to save the image into the user’s uploads. The job then returns an asset, which you can use with other Connect APIs like autofill.
  • The idempotency key is a UUID, held for 24 hours. Retrying a create with the same key returns the original job rather than generating again.

Without asset_upload, remember the download URL expires after 24 hours, so download the image rather than hotlinking it.

Usage notes

  • Starting a job consumes the user’s AI credit allowance. If the user is out of credits the create returns a 429 with credit_quota_exceeded.
  • If you pinned a model and it can’t serve the request right now, the job fails with a model_not_available error code. This can happen at any time, so handle it: retry later, or retry without model and let us pick.
  • Prompts and outputs go through content safety checks. A rejected generation fails with unsafe_input.

Docs & details

Full request and response schemas, plus a live playground, are in the API reference:

Reminder

As this is a preview API, breaking changes may occur. Keep an eye on the [Changelog](Changelog - Canva Developers SDK Documentation) — that’s also where model availability changes and deprecations will show up.

Feedback & questions

If you have feedback or questions about image generation, let us know on this thread.

image_gen_is_on_connect_api
image_gen_is_on_connect_api1024×1024 218 KB

strong text

2 Likes
2

I tested this out and generated an image using the new endpoints it works smoothly! This API update is a game-changer for automating creative workflows and embedding generation directly into custom apps. Being able to programmatically handle image assets opens up so many possibilities. Quick question: are there any plans to support webhook notifications for job completion in future updates, or will polling remain the primary method?:thinking:

images (29)
images (29)452×678 35.2 KB

1 Like
3

Hi Lauren, thanks for trying it out and for the kind words.

Polling the get image generation job endpoint is the supported approach today. Webhook notifications for job completion are on the roadmap. The Connect API already supports webhooks for some events (Webhooks - Webhooks notification reference - Canva Developers SDK Documentation), but image generation is not covered so far. I can’t share a date yet, but we’ll announce it here when it lands.

In the meantime, feedback like yours helps us prioritise, so please keep it coming.