Skip to main content
POST
Generate Slideshow
Create a new slideshow in the authenticated key scope. This is the core content creation endpoint - your OpenClaw agent or automation script generates slideshows here, then publishes them to media-capable accounts via Create Post. generate supports:
  • AI generation from a prompt/product context
  • manual initial slide setup (skip_ai=true)
  • mixed setup with explicit slide_config
  • recreating the format of a Viral Library post for your product (reference)
Generation runs on the same engine as the Genviral app and Vira. The request stays open until the deck is finished (usually one to three minutes) and then returns it. If the deck is still generating after about five minutes, the request answers 504 generation_timeout with the slideshow_id; poll Get Slideshow until generation_status is complete or failed, or retry with the same Idempotency-Key to wait on the same deck again.

Idempotency

Send a unique Idempotency-Key header for each slideshow you intend to create. Retrying the same key with the same body replays the original result. When the header is omitted, Genviral derives a stable key from the credential and request body for backward compatibility, so an identical headerless request is treated as a retry rather than a new generation.

Body Parameters

string
Prompt used for AI text generation. Required unless skip_ai=true or product_id is provided.
string (UUID)
Optional product reference. Must exist in the authenticated key scope.
string (UUID)
Optional global image pack ID. Required whenever any generated slide uses image_pack and no per-slide pack_assignments are provided, unless image_sourcing allows Pinterest sourcing.
string
Optional image sourcing mode. Default: pack (backward compatible).
  • pack — shuffle backgrounds from pack_id or per-slide pack_assignments only
  • pinterest_auto — run the whole-deck Pinterest agent after text generation; pack_id optional
  • pinterest_then_pack — image search like pinterest_auto; a slide the search cannot fill takes an image from its pack_assignments pack or pack_id instead (no extra charge). Without a pack it behaves exactly like pinterest_auto, where an unfilled slide fails the request
object
Optional Viral Library post to recreate for your product or prompt, as { "viral_post_id": "<post id>" }. Genviral analyzes the post once (the first request for a post can take 15–40 seconds longer; that time is part of the same wait) and builds one slide per analyzed source slide: each keeps the source slide’s kind of shot, subject, copy role, copy pattern, and length. The reference is style only: new words are written for your product and every image is sourced by search. The source post’s text and images are never reused.Requires prompt or product_id. Not accepted together with slide_config, slide_count, pack_id, skip_ai: true, or an image_sourcing other than pinterest_auto. Reading the post counts against your Viral Library get rate limit.
number
Optional target slide count (1-10). Default: 5.
string
Optional: educational or personal. Default: educational.
string
Optional: 9:16, 1:1, or 4:5. Default: 4:5.
string
Optional language hint (2-32 chars).
object
Optional text styling defaults.
boolean
Optional. When true, no AI copy is written: slides with text in slide_config.slide_texts or slide_config.slide_text_elements keep it verbatim, and every other slide is image-only. Images are still sourced from your packs, custom images, or Pinterest.
object
Optional explicit per-slide setup.
All slide_config map keys must be 0-based numeric indices in range. image_pack slides must resolve a pack via pack_id, pack_assignments[index], or an image_sourcing mode that allows Pinterest sourcing (pinterest_auto, pinterest_then_pack).

Examples

AI mode (prompt + global pack)

cURL

Pinterest auto mode (image_sourcing=pinterest_auto)

cURL

Recreate a Viral Library post for a product (reference)

cURL

Manual mode (skip_ai=true)

cURL

Response

Returns 201 with the full slideshow object (same structure as Get Slideshow).
Response

Error Responses

  • 400 invalid_json - body is not valid JSON
  • 422 invalid_payload - schema/validation failed
  • 422 pack_empty - a referenced pack is missing, outside key scope, or has no images
  • 404 viral_reference_not_found - the reference post does not exist or is not visible to this credential
  • 422 viral_reference_has_no_images - the reference post has no slide images to analyze
  • 429 rate_limited - a reference request hit the Viral Library get rate limit; see retry_after_seconds
  • 503 viral_reference_analysis_unavailable - the reference post could not be analyzed right now (retryable: true); nothing was charged
  • 403 forbidden_product_access - product_id does not exist or is outside key scope
  • 409 conflict - the Idempotency-Key is in use by a running request (retryable: true) or was used for a different request (retryable: false)
  • 401 - authentication failed (missing/invalid/revoked token)
  • 402 subscription_required - active Creator/Professional/Business plan required
  • 402 insufficient_credits - buy a credit pack at https://www.genviral.io/billing?tab=credits, then retry
  • 403 tier_not_allowed - Scheduler tier cannot use Partner API
  • 500 generate_failed - generation failed; includes slideshow_id when the deck was started
  • 504 generation_timeout - the deck is still generating; poll slideshow_id with Get Slideshow