API Documentation

Getting Started

curl -X GET https://lowkeyviral.com/api/v1/account \
  -H "Authorization: Bearer lkv_sk_your_key_here"

Authentication

All API requests require a Bearer token in the Authorization header. API keys start with lkv_sk_.

Authorization: Bearer lkv_sk_...

Rate Limits

When rate limited you will receive a 429 response with a Retry-After header indicating seconds to wait.

Typical Workflow

Grid Video (2x2 grid)

Slideshow (photo carousel)

Endpoints

Generate AI content briefs from a business description.

Returns 5 briefs per request for both grid and slideshow types.

Example

curl -X POST https://lowkeyviral.com/api/v1/briefs \
  -H "Authorization: Bearer lkv_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A travel app for Gen-Z backpackers"}'

Response

{
  "briefs": [
    {
      "id": "clxyz...",
      "type": "grid",
      "hook": "pov: your euro trip bucket list is about to be god tier",
      "title": "find these hidden gems and more on WanderApp 🌍✈️",
      "caption_style": null,
      "images": [
        { "id": "...", "position": 0, "title": "Hallstatt", "description": "..." },
        { "id": "...", "position": 1, "title": "Kotor", "description": "..." },
        { "id": "...", "position": 2, "title": "Colmar", "description": "..." },
        { "id": "...", "position": 3, "title": "Sintra", "description": "..." }
      ]
    }
  ]
}

Slideshow Example

curl -X POST https://lowkeyviral.com/api/v1/briefs \
  -H "Authorization: Bearer lkv_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A skincare brand for 20-somethings", "type": "slideshow", "slide_count": 6}'

Create a manual content brief with your own images and text.

Example

curl -X POST https://lowkeyviral.com/api/v1/briefs/manual \
  -H "Authorization: Bearer lkv_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "hook": "these coffee shops are insane",
    "title": "Best Coffee Shops",
    "images": [
      { "url": "https://...", "title": "Cafe A", "description": "Cozy vibes" },
      { "url": "https://...", "title": "Cafe B", "description": "Great latte" },
      { "url": "https://...", "title": "Cafe C", "description": "Hidden gem" },
      { "url": "https://...", "title": "Cafe D", "description": "Rooftop" }
    ]
  }'

The render parameter

When render: true, the endpoint triggers rendering after the brief is created (and after image generation, if any images needed to be generated). This is the same as calling POST /api/v1/briefs/:id/render yourself, just bundled into the same request.

For grid briefs: Starts an async Lambda video render. The response includes a render_id — poll GET /api/v1/briefs/:id/render/:renderId/progress every 2-3 seconds until status is "done".

For slideshow briefs: Renders slides synchronously with text overlays. The response includes a slides array with the finished URLs. No polling needed.

Credit cost: +1 render credit on top of whatever else the call costs (image generation, etc.). Image generation credits are only charged for images that need generation (description present, url missing).

render is independent of image generation. You can pass your own image URLs and still use render: true — it will skip image generation and go straight to rendering. Or you can omit render and just have images generated without rendering.

Response

{
  "id": "clxyz...",
  "hook": "these coffee shops are insane",
  "title": "Best Coffee Shops",
  "images": [
    { "id": "...", "position": 0, "title": "Cafe A", "description": "Cozy vibes", "url": "https://...", "rendered_url": null }
  ]
}

When render: true for a grid, the response includes a render_id for polling:

{
  "id": "clxyz...",
  "hook": "...",
  "title": "...",
  "images": [...],
  "render_id": "abc123"
}

When render: true for a slideshow, the response includes a slides array immediately:

{
  "id": "clxyz...",
  "hook": "...",
  "title": "...",
  "images": [...],
  "slides": [
    { "index": 0, "url": "https://generated.lowkeyviral.com/slideshows/briefId/slide-0.jpg" },
    { "index": 1, "url": "https://generated.lowkeyviral.com/slideshows/briefId/slide-1.jpg" }
  ]
}

List all your content briefs.

Query Parameters

Example

curl https://lowkeyviral.com/api/v1/briefs \
  -H "Authorization: Bearer lkv_sk_your_key_here"

Response

{
  "data": [
    {
      "id": "...",
      "hook": "...",
      "title": "...",
      "is_generated": true,
      "video_url": null,
      "images": [...]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get a single content brief by ID.

Example

curl https://lowkeyviral.com/api/v1/briefs/BRIEF_ID \
  -H "Authorization: Bearer lkv_sk_your_key_here"

Response

{
  "id": "clxyz...",
  "type": "slideshow",
  "hook": "...",
  "title": "...",
  "is_generated": true,
  "video_url": null,
  "caption_style": "classic_bold",
  "created_at": "2026-02-12T00:00:00Z",
  "images": [
    { "id": "...", "position": 0, "title": "...", "description": "...", "url": "https://...", "rendered_url": "https://generated.lowkeyviral.com/slideshows/.../slide-0.jpg" }
  ]
}

Delete a content brief and its associated images.

Example

curl -X DELETE https://lowkeyviral.com/api/v1/briefs/BRIEF_ID \
  -H "Authorization: Bearer lkv_sk_your_key_here"

Response

{ "success": true }

Generate images for a brief. Pass render: true to also start rendering once images are ready (same behavior as the render parameter on /briefs/manual).

Example

curl -X POST https://lowkeyviral.com/api/v1/briefs/BRIEF_ID/generate \
  -H "Authorization: Bearer lkv_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image_model": "z_image_turbo",
    "render": true,
    "design": "default",
    "soundtrack": "City Sunshine"
  }'

Response

{
  "id": "clxyz...",
  "hook": "...",
  "title": "...",
  "is_generated": true,
  "video_url": null,
  "created_at": "...",
  "images": [...],
  "render_id": "abc123"
}

When render: true for a slideshow, the response includes rendered slides immediately:

{
  "id": "clxyz...",
  "hook": "...",
  "title": "...",
  "is_generated": true,
  "images": [...],
  "slides": [
    { "index": 0, "url": "https://generated.lowkeyviral.com/slideshows/briefId/slide-0.jpg" },
    { "index": 1, "url": "https://generated.lowkeyviral.com/slideshows/briefId/slide-1.jpg" }
  ]
}

Start rendering. For grid briefs, returns a renderId for polling. For slideshow briefs, returns rendered slides immediately.

Grid Example

curl -X POST https://lowkeyviral.com/api/v1/briefs/BRIEF_ID/render \
  -H "Authorization: Bearer lkv_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"design": "default", "soundtrack": "City Sunshine"}'

Grid Response

{ "render_id": "abc123" }

Slideshow Example

curl -X POST https://lowkeyviral.com/api/v1/briefs/BRIEF_ID/render \
  -H "Authorization: Bearer lkv_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"caption_style": "classic_bold"}'

Slideshow Response

{
  "slides": [
    { "index": 0, "url": "https://generated.lowkeyviral.com/slideshows/briefId/slide-0.jpg" },
    { "index": 1, "url": "https://generated.lowkeyviral.com/slideshows/briefId/slide-1.jpg" }
  ]
}

Poll render progress. Call every 2-3 seconds.

Example

curl https://lowkeyviral.com/api/v1/briefs/BRIEF_ID/render/RENDER_ID/progress \
  -H "Authorization: Bearer lkv_sk_your_key_here"

Responses

In progress:

{
  "type": "progress",
  "progress": 0.45,
  "started_at": "2026-02-12T00:00:00.000Z",
  "elapsed_seconds": 32,
  "stalled": false
}

Completed:

{
  "type": "done",
  "url": "https://s3.us-east-1.amazonaws.com/.../out.mp4",
  "size": 1234567
}

Error:

{
  "type": "error",
  "message": "Render timed out. The Lambda function did not complete in time."
}

Get a presigned URL to upload a custom image.

Supported content_type values: image/jpeg, image/png, image/webp.

Example

curl -X POST https://lowkeyviral.com/api/v1/uploads \
  -H "Authorization: Bearer lkv_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "image/jpeg"}'

Response

{
  "upload_url": "https://...",
  "file_url": "https://generated.lowkeyviral.com/...",
  "content_type": "image/jpeg",
  "max_size": 10485760
}

Get your account info including credits and plan type.

Example

curl https://lowkeyviral.com/api/v1/account \
  -H "Authorization: Bearer lkv_sk_your_key_here"

Response

{
  "credits": 42,
  "plan_type": "PRO",
  "next_reset_date": "2026-03-01T00:00:00Z"
}

Brief Fields

Valid Option Values

Designs

default, withCaptions, noSpaces

Image Models

Total image-generation cost = per-image cost × number of images/slides.

Caption Styles (Slideshow)

Soundtracks

Advertime, And Just Like That, Blippy Trance, Brewing Potions, City Sunshine, Funshine, Happy Whistling Ukulele, I Guess What I'm Trying to Say, La Citadelle, Lukewarm Banjo, Magical Transition, Martini Sunset, Meditating Beat, Night in Venice, River Meditation, Soundtrack From the Starcourt Mall, Strength of the Titans, Study and Relax, Sun Up Gunned Down, The Celebrated Minuet

Credit Costs

Error Codes

All errors return a consistent format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}