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. You write the words on every slide; Genviral plans the deck, sources or generates the images, and lays out your copy unchanged.

​
Image sources

  • 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, use Generate Slideshow with reference instead.

​
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[]
required
1 to 10 slides, in order.
​
string
default:"auto"
auto (default), pack, or ai_from_reference (opt-in, charged per generated image).
​
object
Required when image_source is ai_from_reference, and only accepted then.
​
string
Image pack UUID. Required when image_source is pack, and only accepted then.
​
string
Optional product UUID the slideshow is for.
​
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).

​
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 10 to 15 seconds. 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 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