Resource Guide

Timer Frames

Timer Frames are temporary timer image drafts built for conversational creation flows. Create a draft, make structured visual changes, preview the animated GIF, keep tweaking, then save only when the user approves the final version.

Timer Frame drafts are scoped to your API key and conversationId. Keep the returned timerFrameId and conversationId together for follow-up requests. Use GET /v2/fonts to find the numberFontId for generated timer text.
Treat POST /v2/timer-frames/{timerFrameId}/save as the final commit step. Agents should show the latest preview, ask for confirmation, then save as the last draft call. After save, the timer is live for use in an email campaign or website.
After a timer is saved, use Timers and PATCH /v2/timers/{id}/target-date when you only need to update its live target date.

Create a timer frame

Reference

Create a temporary draft. If conversationId is omitted, the API generates one and returns it. Set numberFontId to use a built-in or uploaded font from the Fonts API.

curl https://dev.niftyimages.com/v2/timer-frames \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_july-campaign",
    "targetDateUtc": "2026-07-04T16:00:00Z",
    "timeZoneId": "America/New_York",
    "width": 600,
    "height": 140,
    "backgroundColor": "#0A2540",
    "numberColor": "#FFFFFF",
    "labelColor": "#B7C4D6",
    "numberFontId": 42,
    "numberBackplate": "ring",
    "backplateColor": "#1A56C4",
    "backplateTrackColor": "#D8E2F0",
    "showLabels": true
  }'

Start over

Reference

Create a fresh draft for a conversation and discard the current draft in that same conversation.

curl https://dev.niftyimages.com/v2/timer-frames \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_july-campaign",
    "targetDateUtc": "2026-07-04T16:00:00Z",
    "startOver": true
  }'

Get a timer frame

Reference

Fetch the current draft state, including the normalized frame JSON, applied changes, save readiness, and preview metadata.

curl "https://dev.niftyimages.com/v2/timer-frames/{timerFrameId}?conversationId=conv_july-campaign" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Update a timer frame

Reference

Apply structured visual changes. You can send targeted fields, including numberFontId, or replace the full frame JSON when needed.

curl -X PATCH https://dev.niftyimages.com/v2/timer-frames/{timerFrameId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_july-campaign",
    "numberBackplate": "pie",
    "backgroundColor": "#FFFFFF",
    "numberColor": "#0A2540",
    "numberFontId": 42,
    "numberFontSizeDelta": 8,
    "showLabels": false
  }'

Render a preview

Reference

Use the short-lived preview.url returned from create, get, and update responses to render the current animated GIF preview.

curl "https://dev.niftyimages.com/v2/timer-frame-previews/{token}/conv_july-campaign/{timerFrameId}" \
  --output preview.gif

Save a timer frame

Reference

Save the current draft as a live timer image only after the user confirms the final preview. A successful save returns the saved image id, name, image type, and draft identifiers. This should be the last Timer Frame draft call in the conversation.

curl -X POST https://dev.niftyimages.com/v2/timer-frames/{timerFrameId}/save \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_july-campaign",
    "name": "July launch countdown"
  }'

Delete a timer frame

Reference

Delete a temporary draft when the conversation no longer needs it.

curl -X DELETE "https://dev.niftyimages.com/v2/timer-frames/{timerFrameId}?conversationId=conv_july-campaign" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"