Render API · v1

Render the scene. Ship the file.

Turn TheFake scene data into screenshots and social-ready videos from your own scripts, MCP tools, queues, or publishing pipeline.

$15/month. No trial. Access activates after payment.

publish-scene.sh
curl -X POST https://www.thefake.design/api/v1/video-renders \
  -H "x-api-key: $THEFAKE_API_KEY" \
  -H "Idempotency-Key: publish-scene-001" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "chat-vertical",
    "durationSeconds": 5,
    "fps": 30,
    "scale": 1,
    "format": "mp4",
    "scene": {
      "platform": "whatsapp",
      "messages": [
        {"id": "question", "type": "text", "text": "publish it?", "direction": "incoming", "status": "read"},
        {"id": "answer", "type": "text", "text": "already queued.", "direction": "outgoing", "status": "read"}
      ]
    }
  }'
202 Accepted
{
  "success": true,
  "data": {
    "id": "render_01J...",
    "status": "queued",
    "creditsUsed": 1,
    "statusUrl": "/api/v1/video-renders/render_01J...",
    "downloadUrl": null
  }
}

200 credits

Included every month

PNG + JPEG

Synchronous screenshots

MP4 + WebM

Private video jobs

30 templates

Chat, post, story, email

Quickstart

From payment to a saved image.

Subscribe to API Starter, create a scoped key, then send one JSON request. Screenshots return the file immediately; video creates return a private job.

  1. 01

    Subscribe

    Start API Starter for $15/month. Access activates after Polar confirms payment.

  2. 02

    Create a key

    Name the integration, choose screenshot or video scopes, and copy the secret once.

  3. 03

    Render

    Send the key in x-api-key, add an idempotency key, and save or poll the result.

curl · screenshot ready
curl -X POST https://www.thefake.design/api/v1/screenshots \
  -H "x-api-key: $THEFAKE_API_KEY" \
  -H "Idempotency-Key: tender-summary-001" \
  -H "Content-Type: application/json" \
  -o tender-summary.png \
  -d '{
    "template": "chat-square",
    "frameIndex": 90,
    "format": "png",
    "scale": 2,
    "filename": "tender-summary.png",
    "scene": {
      "platform": "imessage",
      "messages": [
        {
          "id": "question",
          "type": "text",
          "text": "What did the department spend?",
          "direction": "incoming",
          "status": "read"
        },
        {
          "id": "answer",
          "type": "text",
          "text": "$4.2m across 18 awarded tenders.",
          "direction": "outgoing",
          "status": "read"
        }
      ]
    }
  }'
javascript · screenshot ready
const renderRequest = {
  template: "chat-square",
  format: "png",
  scale: 2,
  scene: {
    platform: "imessage",
    messages: [
      {
        id: "finding",
        type: "text",
        text: "$4.2m across 18 awarded tenders.",
        direction: "outgoing",
        status: "read"
      }
    ]
  }
};

const response = await fetch(
  "https://www.thefake.design/api/v1/screenshots",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.THEFAKE_API_KEY,
      "Idempotency-Key": "tender-summary-001",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(renderRequest)
  }
);

if (!response.ok) {
  throw new Error(await response.text());
}

const image = Buffer.from(await response.arrayBuffer());

Authentication

Use x-api-key for server integrations. A bearer value beginning with tf_ is also accepted. Never expose a key in browser code or a public repository.

Scopes and rotation

Keys can carry screenshots, videos, or both. Create a replacement before revoking an old key. Revocation takes effect on the next request.

MCP review boundary

Expose render creation as a server-side MCP tool, then return the file or job to the chat for review. Keep the final social publish action separate so a person approves the output.

Scene data

Send only the scene fields you want to change.

The scene object is merged with each template's working defaults. Start with the content, then add headers, settings, participants, media, or platform-specific details.

scene · chat ready
{
  "platform": "whatsapp",
  "messages": [
    {
      "id": 1,
      "type": "text",
      "text": "Can you summarize the result?",
      "direction": "incoming",
      "status": "read"
    },
    {
      "id": 2,
      "type": "photo",
      "mediaUrl": "https://cdn.example.com/chart.png",
      "text": "Here is the spending breakdown.",
      "direction": "outgoing",
      "status": "read"
    }
  ],
  "isGroupChat": false,
  "settings": {
    "darkMode": false,
    "showStatusBar": true
  }
}

Content families

FamilyTemplatesRequired scene fieldsOptional scene fields
Chatchat-*platform, messagesheader, settings, participants, isGroupChat, wallpaper, showDeviceFrame
Postpost-*postsettings, showDeviceFrame
Commentscomments-*postsettings, commentPlatform, showDeviceFrame
Storystory-*, tiktok-story-*storystorySlides, settings, showDeviceFrame
Emailemail-threademailplatform, settings, showDeviceFrame
X featuresx-feature-*modeblock, suspension, replyChain, profile, showDeviceFrame

Chat message fields

Every message needs an ID, type, direction, and delivery status.

Image fields must use a direct media URL, not a webpage URL.

FieldTypeMeaning
idstring | numberUnique message identifier within the request.
typestringtext, photo, video, audio, view_once, typing_pause, call_event, deleted, or system_event.
directionstringoutgoing for the account owner, incoming for another participant.
statusstringnone, sent, delivered, or read.
textstringRequired for text messages and optional as a media caption.
mediaUrlstringDirect media URL for photo or supported media messages.
durationSecondsnumberDuration for video, audio, and typing-pause messages.
sentAtstringOptional local ISO-style date and time displayed on the message.
senderIdstringParticipant ID for received messages in group chats.

Scene recipes

Use these as minimal starting shapes for the other content families.

Post and comments post-*, comments-*
scene · post and comments ready
{
  "post": {
    "id": 1,
    "postType": "linkedin_post",
    "author": {
      "name": "Avery Morgan",
      "handle": "averymorgan",
      "isVerified": true
    },
    "text": "Five findings from this week's tender data.",
    "timestamp": "2m",
    "metrics": {
      "likes": 42,
      "reposts": 5,
      "comments": 3
    },
    "comments": []
  },
  "settings": {
    "showStatusBar": true,
    "showNotch": false,
    "showComments": true
  }
}
Story story-*, tiktok-story-*
scene · story ready
{
  "story": {
    "backgroundMedia": "",
    "author": {
      "username": "averymorgan",
      "isVerified": true
    },
    "timeAgo": "2h",
    "gradientIndex": 2,
    "textOverlays": [
      {
        "id": "finding-1",
        "text": "$4.2m across 18 tenders",
        "xPercent": 50,
        "yPercent": 48,
        "style": "strong",
        "fontSize": 28,
        "align": "center"
      }
    ]
  },
  "settings": {
    "showStatusBar": false
  }
}
Email email-thread
scene · email ready
{
  "platform": "gmail",
  "email": {
    "subject": "Re: Tender analysis",
    "attachmentName": "findings.pdf",
    "folderLabel": "Inbox",
    "isStarred": false,
    "participants": [
      {"id": "analyst", "name": "Avery", "email": "avery@example.com"},
      {"id": "editor", "name": "Jordan", "email": "jordan@example.com"},
      {"id": "lead", "name": "Sam", "email": "sam@example.com"}
    ],
    "messages": [
      {
        "id": "email-1",
        "senderId": "analyst",
        "toIds": ["editor"],
        "ccIds": ["lead"],
        "sentAt": "2026-08-04T10:15",
        "body": "The spending summary is ready for review."
      }
    ]
  }
}

Endpoint reference

A small surface with predictable responses.

All authenticated endpoints are owner-scoped. A key can only poll, download, or cancel jobs created by the same account.

GET/api/v1/templatesPublic

List templates and supported output types.

POST/api/v1/screenshotsscreenshots

Render and stream a PNG or JPEG.

POST/api/v1/video-rendersvideos

Create an asynchronous MP4 or WebM job.

GET/api/v1/video-renders/{renderId}videos

Refresh and return a private job.

GET/api/v1/video-renders/{renderId}/downloadvideos

Stream a completed video.

DELETE/api/v1/video-renders/{renderId}videos

Cancel and remove a job.

POST /screenshots

Returns a PNG or JPEG binary with 200 OK. Save the body directly instead of parsing JSON.

FieldTypeRequiredDescription
templatestringYesA template ID returned by GET /api/v1/templates.
sceneobjectYesContent and presentation fields merged with the template defaults.
frameIndexintegerNoFrame to capture. Defaults to the final frame.
formatpng | jpegNoOutput format. Defaults to png.
scalenumberNoRender scale from 1 to 4. Defaults to 2.
filenamestringNoDownload filename, up to 120 characters.
POST /video-renders

Returns a JSON job with 202 Accepted. Poll its status URL until a download URL appears.

FieldTypeRequiredDescription
templatestringYesA video-capable template ID.
sceneobjectYesContent and presentation fields merged with the template defaults.
durationSecondsnumberYesVideo duration in seconds, from more than 0 up to 600.
fpsintegerNoFrame rate from 1 to 60. Defaults to 30.
scalenumberNoRender scale from 1 to 4. Defaults to 1.
formatmp4 | webmNoOutput format. Defaults to mp4.
filenamestringNoDownload filename, up to 120 characters.
curl · create video ready
curl -X POST https://www.thefake.design/api/v1/video-renders \
  -H "x-api-key: $THEFAKE_API_KEY" \
  -H "Idempotency-Key: tender-video-001" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "chat-vertical",
    "durationSeconds": 5,
    "fps": 30,
    "scale": 1,
    "format": "mp4",
    "scene": {
      "platform": "whatsapp",
      "messages": [
        {
          "id": 1,
          "type": "text",
          "text": "Ready to publish?",
          "direction": "incoming",
          "status": "read"
        }
      ]
    }
  }'
202 · job response ready
{
  "success": true,
  "requestId": "req_01J...",
  "data": {
    "id": "render_01J...",
    "status": "queued",
    "template": "chat-vertical",
    "format": "mp4",
    "fps": 30,
    "scale": 1,
    "durationSeconds": 5,
    "creditsUsed": 1,
    "progressPercent": 0,
    "statusUrl": "/api/v1/video-renders/render_01J...",
    "downloadUrl": null
  }
}
curl · poll and download ready
# Poll until status is completed or failed
curl https://www.thefake.design/api/v1/video-renders/render_01J... \
  -H "x-api-key: $THEFAKE_API_KEY"

# Download a completed job
curl https://www.thefake.design/api/v1/video-renders/render_01J.../download \
  -H "x-api-key: $THEFAKE_API_KEY" \
  -o tender-summary.mp4

# Cancel and remove a job
curl -X DELETE https://www.thefake.design/api/v1/video-renders/render_01J... \
  -H "x-api-key: $THEFAKE_API_KEY"
queued

Accepted and waiting for renderer capacity.

rendering

Frames are being composed and encoded.

completed

downloadUrl is ready for the same API key.

failed

No output is available and reserved credits are refunded.

Template catalog

Thirty templates, one discovery endpoint.

Call GET /api/v1/templates at runtime to discover the current catalog. Each result declares whether it supports screenshots, videos, or both.

Chat

6 templates
  • chat-mobile

    Mobile chat thread export for short-form screenshots and animated message stories.

    mobile · screenshots + videos
  • chat-desktop

    Desktop chat layout for browser-style or workstation-style conversation mockups.

    desktop · screenshots + videos
  • chat-vertical

    Vertical chat composition optimized for short-form video platforms.

    mobile · screenshots + videos
  • chat-portrait

    Portrait chat composition sized for feed-style social posts.

    mobile · screenshots + videos
  • chat-square

    Square chat composition for 1:1 social placements.

    mobile · screenshots + videos
  • chat-landscape

    Wide chat composition for YouTube, presentations, and embeds.

    desktop · screenshots + videos

Email

1 templates
  • email-thread

    Mobile email thread composition for Gmail, Apple Mail, Outlook, and redacted screenshots.

    mobile · screenshots

Story

13 templates
  • story-mobile

    Mobile full-screen story composition with overlays and viewer context.

    mobile · screenshots + videos
  • story-desktop

    Desktop story composition for previewing story visuals in a wider interface.

    desktop · screenshots + videos
  • story-vertical

    Vertical story composition optimized for short-form story sharing.

    mobile · screenshots + videos
  • story-portrait

    Portrait story composition sized for feed-style social posts.

    mobile · screenshots + videos
  • story-square

    Square story composition for 1:1 social placements.

    mobile · screenshots + videos
  • story-landscape

    Wide story composition for YouTube, presentations, and embeds.

    desktop · screenshots + videos
  • tiktok-story-mobile

    TikTok-style mobile story composition for creator-first vertical content.

    mobile · screenshots + videos
  • tiktok-story-desktop

    Desktop TikTok story composition for wider preview and review workflows.

    desktop · screenshots + videos
  • tiktok-story-vertical

    Vertical TikTok story composition optimized for short-form sharing.

    mobile · screenshots + videos
  • tiktok-story-portrait

    Portrait TikTok story composition sized for feed-style social posts.

    mobile · screenshots + videos
  • tiktok-story-square

    Square TikTok story composition for 1:1 social placements.

    mobile · screenshots + videos
  • tiktok-story-landscape

    Wide TikTok story composition for landscape placements and embeds.

    desktop · screenshots + videos
  • tiktok-reply

    Standalone TikTok reply-to-comment sticker composition for creator hooks and mockups.

    mobile · screenshots + videos

X features

2 templates
  • x-feature-mobile

    Mobile X-style post and feature composition for feed or thread exports.

    mobile · screenshots + videos
  • x-feature-desktop

    Desktop X-style composition for wider social feed previews.

    desktop · screenshots + videos

Post

5 templates
  • post-mobile

    Standard social post composition for feed-based screenshot and video exports.

    mobile · screenshots + videos
  • post-square

    Square post composition optimized for 1:1 social content previews.

    mobile · screenshots + videos
  • post-portrait

    Portrait post composition for taller social placements and story-like crops.

    mobile · screenshots + videos
  • post-vertical

    Story-style post composition for immersive vertical placements.

    mobile · screenshots + videos
  • post-landscape

    Wide post composition for landscape placements and embedded previews.

    desktop · screenshots + videos

Comments

3 templates
  • comments-mobile

    Comments thread composition for reply chains, reactions, and community views.

    mobile · screenshots + videos
  • comments-vertical

    Vertical comments thread composition optimized for short-form story placements.

    mobile · screenshots + videos
  • comments-landscape

    Wide comments thread composition for desktop reviews and embedded use cases.

    desktop · screenshots + videos

Credits and limits

Know the cost before the render starts.

API Starter includes 200 monthly credits. Monthly credits are consumed first, then purchased credits. A rejected create or failed render returns its reservation.

Credit cost
OutputSettingsCost
ScreenshotScale 1 or 21 credit
ScreenshotScale 32 credits
ScreenshotScale 44 credits
Video5 seconds, 30 FPS, scale 11 credit
VideoHigher FPS or scaleRounded up from duration × FPS × scale²

Video formula: ceil(seconds ÷ 5 × FPS ÷ 30 × scale²). Purchased packs add 200 credits for $10 and remain valid for 12 months.

Per-account rate limits
OperationLimit
Screenshot renders20 per minute
Video creates5 per minute
Video status and cancellation60 per minute
Video downloads20 per minute

Read the rate-limit headers on every response. When blocked, wait for Retry-After instead of using a fixed delay.

Response headers

HeaderMeaning
X-Request-IdTrace identifier to include in support requests.
X-RateLimit-LimitMaximum requests in the current window.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetWindow reset time as Unix milliseconds.
X-TheFake-Credits-UsedCredits reserved by this create request.
X-TheFake-Credits-RemainingTotal monthly and extra credits remaining.
X-TheFake-Credits-ResetMonthly credit reset time as Unix milliseconds.
X-TheFake-TemplateReadable template ID used for a screenshot render.
X-TheFake-Frame-IndexFrame index captured for a screenshot render.
Idempotent-Replayedtrue when a completed response was replayed.
Retry-AfterSeconds to wait after a 409, 429, or temporary renderer error.

Errors and retries

Branch on the code. Log the request ID.

JSON errors always include a stable code and a support-safe request ID. Preserve both in logs, then retry only the states described below.

402 · error response ready
{
  "success": false,
  "requestId": "req_01J...",
  "error": {
    "message": "This render needs 4 credits, but only 2 remain.",
    "code": "insufficient_credits"
  }
}
HTTPCodeMeaning
400invalid_body / invalid_requestMalformed JSON or an invalid render field.
400invalid_idempotency_keyThe key is outside the supported length or character set.
401authentication_required / invalid_api_keyCredentials are missing, invalid, or revoked.
402subscription_requiredThe account does not have an active Render API subscription.
402insufficient_creditsThe account does not have enough credits for the render.
409idempotency_in_progressThe same create request is still running.
409render_not_readyThe video exists but is not ready to download.
410idempotency_response_expiredThe original response is no longer replayable.
413payload_too_largeThe JSON request body exceeds 5 MB.
422idempotency_key_mismatchThe same key was reused with different JSON.
429rate_limitedThe account exceeded an endpoint limit.
503renderer_busy / renderer_unavailableCapacity is temporarily unavailable.
504renderer_timeoutThe renderer did not finish within its timeout.

Idempotency keys

Use 8 to 255 characters from letters, numbers, underscore, hyphen, period, slash, or colon. Keep one key per logical create.

Retry policy

Retry 409 in-progress, 429, 503, and 504 responses using Retry-After when present. Reuse the same idempotency key.

Replay window

Completed create responses are replayable for 24 hours when the body is cacheable. A replay never creates another credit reservation.

Start API Starter

Access and keys

Pay, create a key, start rendering.

API Starter includes 200 monthly render credits for $15/mo. Every paying customer receives immediate access, with no application or approval step.

API Starter

Render when the story is ready.

One paid plan for human-reviewed workflows, small publishing queues, and the first automation that saves you from another copy and paste.

  • 200 render credits every month
  • Screenshots and asynchronous video
  • Scoped keys you can revoke anytime

Monthly, cancel anytime

$15/mo

Included200 credits

A standard screenshot uses 1 credit. Standard 30 FPS video uses 1 credit per 5 seconds. Higher scale and frame rates use more.

No free tier. No trial. Pro access is not included.

Before you automate publishing

Create responsibly. Review platform rules.

TheFake creates fictional mockups. Do not use exports to impersonate people, fabricate harmful evidence, or mislead audiences.

Acceptable use