Skip to main content
POST
Starts generating a slideshow in the background and returns its slideshow_id right away with 202 Accepted. Generation typically takes a few minutes. Poll Get Slideshow with the returned id until generation_status is complete or failed. A complete slideshow can then be edited, rendered, and posted like any other. A request takes one of two shapes:
  • Your slides. You write the words on every slide in slides; Genviral plans the deck, sources or generates the images, and lays out your copy unchanged.
  • Recreate a Viral Library post. Leave out slides and send reference with a product_id or prompt. Genviral analyzes that post’s slides, writes new copy about your product or prompt in its format, and finds new images by search, exactly like Generate Slideshow with reference, but without waiting for the deck. The post’s own words and images are never reused. A recreation refuses pack_id, title, and any image_source other than auto. Reading the reference counts against your Viral Library get rate limit, and only slideshow posts can be recreated.

Image sources (your slides)

  • auto (the default) finds a matching image for each slide from its copy and image_subject, searching Genviral’s curated image library first and Pinterest second.
  • pack uses images from one of your image packs.
  • ai_from_reference is an opt-in premium mode that generates every slide image, using the slide images of one Viral Library post as a style reference. Slide 1 is styled on the post’s slide 1, slide 2 on its slide 2, and so on, cycling when your deck is longer. The reference guides look and composition only; its images and copy are never reused. Reading the reference counts against your Viral Library get rate limit.
To recreate a Viral Library post with Genviral-written copy and searched images, leave out slides (see above).

Credits

Credits are charged when generation starts, and credits_charged reports the charge. Each generated image (ai_from_reference) is charged at the slideshow image rate; auto and pack slides are not charged per image. If generation fails, credits for slides that were not produced are refunded.

Idempotency

Idempotency-Key is required and is scoped to the API key (or MCP grant) that sends it.
  • Retrying with the same key and the same body returns the original 202 response, including its original credits_charged, and never starts or charges a second generation. The replayed generation_status is the status at start time; poll GET /slideshows/{slideshowId} for the current one.
  • Reusing a key with a different body returns 409 idempotency_key_reused.
  • A request that is refused (for example 402 or 422) does not consume its key, so you can fix the problem and retry with the same key.
  • To try again after a generation finished with generation_status: "failed", send a new key.

Body Parameters

object[]
1 to 10 slides, in order. Required unless you recreate reference.
string
default:"auto"
auto (default), pack, or ai_from_reference (opt-in, charged per generated image).
string
Recreation only: what the new deck is about when there is no product_id (up to 8000 characters). Refused alongside slides.
object
With slides, required when image_source is ai_from_reference, and only accepted then. Without slides, the post to recreate.
string
Image pack UUID. Required when image_source is pack, and only accepted then.
string
Optional product UUID the slideshow is for. A recreation needs this or prompt.
string
default:"9:16"
9:16, 3:4, 1:1, or 4:5.
string
Optional language of your copy, such as en or de.
string
Optional display title for the slideshow (up to 200 characters). Not accepted for a recreation.

Response

string
The slideshow being generated. Poll it with Get Slideshow.
string
generating or, when replaying a finished request, complete.
number
Credits charged for this generation.

Polling

Check data.generation_status every 4 to 15 seconds. While it is generating, data.generation_phase names the current step (researching, writing, images, assembling) for progress UI. When it is failed, data.generation_failure holds a stable code and a short message.

Error Responses

  • 400 invalid_json - request body is not valid JSON
  • 400 invalid_request - Idempotency-Key header is missing or longer than 255 characters
  • 401 - authentication failed (missing/invalid/revoked token)
  • 402 insufficient_credits - not enough credits for this generation
  • 403 product_not_accessible - the product is not accessible to this key
  • 404 viral_reference_not_found - the Viral Library post does not exist
  • 409 idempotency_key_reused - this Idempotency-Key was already used with a different body
  • 409 request_in_progress - an identical request with this key is still being processed; retry shortly
  • 422 invalid_payload - body failed validation (see issues)
  • 422 viral_reference_has_no_images - the Viral Library post has no slide images to reference
  • 422 viral_reference_not_slideshow - the Viral Library post is a video; only slideshow posts can be recreated
  • 422 pack_not_usable - the pack is not accessible or has no images
  • 429 rate_limited - Viral Library get limit reached; wait retry_after_seconds
  • 502 generation_enqueue_failed - generation could not be started; retry with the same key
  • 503 viral_reference_analysis_unavailable - the post could not be analyzed right now; retry with the same key shortly