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