Guides

Generate screenshots

The end-to-end path: onboard an app from its store URL, submit a generation job, tune it with a device, a narrative and a caption style, then poll it to completion.

Onboard an app

Start by turning a store listing into an appId. Pass an iOS URL, an Android URL, or both — richer input yields better copy. Optionally add extraContext to steer tone or highlight a feature.

cURL

curl -s https://api.applistinglab.com/api/v1/public/v1/apps \
  -H "Authorization: Bearer $APP_LISTING_LAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "iosUrl": "https://apps.apple.com/app/id1234567890",
    "androidUrl": "https://play.google.com/store/apps/details?id=com.example.app",
    "extraContext": "Lead with the offline mode; audience is runners."
  }'

Choose a device

The device field sets the frame and output dimensions. Generate one set per device you need to ship.

iphone-69 — iPhone 6.9" (15/16 Pro Max)
iphone-67 — iPhone 6.7"
iphone-65 — iPhone 6.5"
ipad-pro — iPad Pro
android-phone — Android phone
android-tablet — Android tablet

Set the length: count vs. narrative

For a quick set, pass count (1–10, default 5) and the API composes a sensible sequence. For a deliberate story, pass a narrativeId — a catalogue slug such as standard-launch — which defines the slides and their roles. A narrativeId overrides count.

Not sure which narrative to use? Design a set visually in the Studio first — the slug it produces is the same narrativeId you pass here.

Tune the captions

captionStyle sets the voice and captionLength (short or long) sets how much text sits on each frame. Available styles:

aso-expert
search-intent
outcome
emoji
direct
friendly
inspire
persuasive

Both are optional — they default to aso-expert and short.

cURL — full request

curl -s https://api.applistinglab.com/api/v1/public/v1/screenshots \
  -H "Authorization: Bearer $APP_LISTING_LAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "665f0a2b9c1e4d0012ab34cd",
    "device": "iphone-67",
    "count": 5,
    "captionStyle": "outcome",
    "captionLength": "short"
  }'

The response returns a jobId and your credit usage. Each screenshot set costs 5 credits, charged when the job is accepted:

response

{
  "jobId": "77a1b2c3d4e5f6a7b8c9d0e1",
  "credits": { "cost": 5, "remaining": 95 }
}

Poll to completion

Generation is asynchronous. Poll /public/v1/jobs/{id} until status leaves queued/running. A finished job carries the set in result; a failed one carries a message in error.

response — succeeded

{
  "id": "77a1b2c3d4e5f6a7b8c9d0e1",
  "status": "succeeded",
  "result": {
    "device": "iphone-67",
    "slides": [ { "caption": "…", "role": "hook", "imageUrl": "…" } ]
  },
  "error": null
}

Polling tips

Poll every ~2 seconds and cap it with a timeout. Sets usually finish within a minute; back off if you're running many jobs at once.

For the exact schema of every request and response, see the API reference.