Generating content
Generation endpoints divide by how long they take. An image comes back in one call, while a presentation is a pipeline you drive across several. Knowing which you are dealing with is most of the integration work.
Everything on this page runs a model, so everything costs
credits and counts against the expensive rate-limit
tier.
Queue and poll
This is the pattern for anything slow, and it is worth learning once:
- POST the request. It answers 202 Accepted with an identifier: the work has been queued, not done.
- Poll the resource until its status says it finished.
- Read the result off the same resource.
A 202 is neither a failure nor a completion. If your client treats any 2xx as "done" and reads the body for output, this is where it breaks.
Images
Code
Ten aspect ratios are available, from 1:1 through 21:9, and they are listed in the
reference.
The generated image is stored like any other file, with the prompt kept alongside it, so generated images stay findable later rather than only being downloadable at the moment of creation.
They live in the generated repository (everything the platform produced, as against the
media library of what people uploaded), so this lists them:
Code
The free-text search covers their prompts, and contentType narrows to image or
infographic. An image generated inside a conversation also belongs to that conversation
and is returned by GET /threads/{id}/files.
One consequence: generated images never get analysis embeddings, so similar-image search returns an empty list for them. That is expected rather than a fault.
Edit images
Three operations work on images already in the library. All are under designs and all are gated on module-design:
POST /designs/remove-background | Knocks out the background of file_id. |
POST /designs/edit-image | Inpainting. Send mode (erase or fill), a PNG mask marking the region, and a prompt for what to put there. Only what the mask covers is regenerated. |
POST /designs/generate-image | Generates for a design. With transparent: true the subject is generated against a knocked-out backdrop, so it sits over the design rather than in a box. |
POST /designs/generate-from-background goes the other way: hand it a background
image and it builds a design around it, given a platform and optional
instructions and caption.
A design's files
Code
Returns what belongs to one design: the assets placed on it and the previews rendered from it. The design's own access rules apply on top of each file's, so a caller who cannot open the design does not receive its assets either.
Design categories
Designs are filed into the workspace's own taxonomy. GET /design-categories lists it
(every workspace starts with a small set it can rename or remove), PUT /design-categories replaces it, and PUT /designs/{id}/categories files one design.
Category ids appear on the design as de_categories.
Infographics
Two generators produce genuinely different results from the same brief:
Code
POST /studio/generate-infographic | Produces HTML and a PNG of it, linked as one file. |
POST /studio/generate-infographic-native | Produces a design: real text layers and real chart objects, editable in the design editor. Requires module-design. |
The native form's charts stay bound to the data they were built from, so refreshing one re-reads the source instead of redrawing a picture. Use the first for a one-off, and the second when someone will edit the result or it must stay current.
data.kind is none, text, file or ds, the last pointing at a knowledge
base. GET /studio/infographic-options lists the sizes and styles the
composer accepts; read it rather than hard-coding the list.
Schedule a refresh
Code
Re-reads the data source on a daily, weekly or monthly cadence and posts a new revision
each time. POST /infographics/{id}/refresh runs one immediately. Only the figures
change; the design does not drift.
Only an infographic with a stored brief can be scheduled, since without one there is nothing to regenerate from.
GET /infographics/{id}/versions lists revisions, so a figure that changed can be traced.
download-png and download-html fetch the output, snapshot-png renders an edited
version, and to-design converts a picture into an editable design.
Presentations
The only true pipeline here, marked beta and gated on module-ppt.
Code
Plan first. POST /presentations/plan turns a brief and a template into a proposed
outline and saves it onto the draft:
Code
Nothing is generated yet: this is the step where the structure is reviewed. Then generate, passing the plan back:
Code
That answers 202. Poll GET /presentations/{id}, which carries ppt_job_status and,
once finished, ppt_job_output_file_id: the deck, downloadable like any other file.
Fix a single slide
Regenerating a whole deck because one image is wrong is rarely what you want:
POST /presentations/{id}/images/regenerate | Takes slideIndex and slotName. Finds the best library photo for that slide and generates a fresh image seeded by it. |
POST /presentations/{id}/images/select | Choose a different image by hand. |
POST /presentations/{id}/rebuild | Rebuilds the file from current content, including every image override. |
Both image operations are recorded as overrides on the same terms, so a rebuild preserves them. The loop is: generate, fix the slides that need it, then rebuild.
POST /presentations/draft saves work in progress, and duplicate and rename do what
their names suggest.
Which endpoint for which job
| You want | Use |
|---|---|
| A new image, now | POST /studio/generate-image |
| An image without its background | POST /designs/remove-background |
| To change part of an image | POST /designs/edit-image |
| A chart-style graphic, one-off | POST /studio/generate-infographic |
| A chart-style graphic someone will edit or that must stay current | POST /studio/generate-infographic-native + a schedule |
| A deck | plan → POST /presentations → poll |
Next steps
- Usage and credits explains what all of this costs and how to watch it.
- AI enrichment covers the analysis that makes generated files findable.
- Organizing and finding assets shows where generated output lands.