Generate a slideshow (AI, async)

POST

/public/v1/slides/generate

curl --request POST \
  --url https://api.loomta.com/public/v1/slides/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "platformIds": [ "8b2c1f4a-77d0-4e2c-9a1e-5c3b2a1d0e4f" ], "topic": "Why indie devs love our app", "slideCount": 4, "mode": "draft" }'

• Production

The hands-off endpoint: give it a topic and it generates the captions + image prompts, generates an AI image for each slide, composites the captions, and creates the post (draft / scheduled / now, per mode) — all server-side. Advanced callers can instead pass a pre-built slides array (caption + imagePrompt each) to skip caption generation. Provide exactly one of topic or slides.

Async: returns a jobId immediately; generation runs in the background (batch; usually minutes). Poll GET /slides/generate/{jobId} until DONE, then read postGroupId. Spends one caption credit (topic path only, charged immediately on generation) plus one image credit per slide (charged on success); the Free plan includes 0 image credits. Image-credit affordability is checked before caption generation runs, so a workspace with no image credits gets 402 immediately without spending a caption credit.

Authorizations

• apiKey

Request Body^required

Media typeapplication/json

Provide exactly one of topic (we generate the captions + image prompts for you) or slides (you supply them, e.g. from POST /slides/caption with imagePrompt: true).

object

platformIds

required

Required. Platform IDs the finished post targets.

Array<string>

>= 1 items

topic

Required unless slides is given. Brief to generate captions + image prompts from. Charges one caption credit.

string

>= 1 characters <= 500 characters

slideCount

Optional (default 6). Number of slides to generate on the topic path.

integer

default: 6 >= 3 <= 10

content

Optional. The overall post caption. On the topic path, falls back to the generated caption when omitted. Required-ish on the slides path (omit to post with no caption).

string

>= 1 characters

language

Optional (default is the workspace setting). Language code for generated text, e.g. en, vi.

string

>= 2 characters <= 35 characters

slideLength

Optional (default is the workspace setting). How much text per slide (topic path).

string

Allowed values: short medium long

slides

Required unless topic is given. Pre-generated captions + image prompts.

Array<object>

>= 1 items <= 35 items

object

index

required

integer

caption

required

Baked onto the generated image.

string

>= 1 characters <= 500 characters

imagePrompt

required

Prompt to generate this slide’s image.

string

>= 1 characters <= 1000 characters

mode

required

Required. How the resulting post is created once images are ready. draft (recommended) lets you review before publishing; schedule requires scheduledFor.

string

Allowed values: draft now schedule

scheduledFor

ISO 8601. Required when mode is schedule; ignored otherwise.

string format: date-time

textStyleId

Optional (default is the workspace setting). Caption font-style preset.

string

Allowed values: tiktok-sans anton montserrat poppins league-spartan

captionSize

Optional (default is the workspace setting, or medium). Caption size.

string

Allowed values: small medium large

settings

Optional (default {}). Provider-specific settings for the created post (e.g. TikTok privacy).

object

key

additional properties

any

Examples

Hands-off from a topic (recommended)

{
  "platformIds": [
    "8b2c1f4a-77d0-4e2c-9a1e-5c3b2a1d0e4f"
  ],
  "topic": "Why indie devs love our app",
  "slideCount": 4,
  "mode": "draft"
}

From pre-generated captions + prompts

{
  "platformIds": [
    "8b2c1f4a-77d0-4e2c-9a1e-5c3b2a1d0e4f"
  ],
  "content": "4 reasons indie devs keep coming back 👇",
  "mode": "draft",
  "slides": [
    {
      "index": 0,
      "caption": "The tool that ships with you",
      "imagePrompt": "A glowing laptop on a cluttered indie dev desk at night, cinematic"
    },
    {
      "index": 1,
      "caption": "Zero-config setup",
      "imagePrompt": "A clean terminal window with a single command, minimalist"
    }
  ]
}

Responses

200

The generation job was queued.

Media typeapplication/json

object

jobId

required

string

status

required

string

Example

{
  "status": "WAITING"
}

400

The request body failed validation.

Media typeapplication/json

object

code

required

A stable, machine-readable error code to branch on.

string

message

required

A human-readable description.

string

details

Optional structured detail (for example Zod validation issues).

Example

{
  "code": "invalid_request",
  "message": "The request payload is invalid.",
  "details": [
    {
      "path": [
        "slideCount"
      ],
      "message": "Number must be greater than or equal to 3"
    }
  ]
}

401

The API key is missing or invalid.

Media typeapplication/json

object

code

required

A stable, machine-readable error code to branch on.

string

message

required

A human-readable description.

string

details

Optional structured detail (for example Zod validation issues).

Examples

{
  "code": "missing_api_key",
  "message": "A Bearer API key is required."
}

{
  "code": "invalid_api_key",
  "message": "The API key is invalid."
}

402

The account’s monthly image credit allowance is exhausted.

Media typeapplication/json

object

code

required

A stable, machine-readable error code to branch on.

string

message

required

A human-readable description.

string

details

Optional structured detail (for example Zod validation issues).

Example

{
  "code": "ai_image_limit_reached",
  "message": "Your plan includes 0 AI images per month. Upgrade your plan for more."
}