ReelGuud API

Authentication

Every API request is authenticated with an API key. Keys start with rg_live_ and are sent as a bearer token in the Authorization header:

Authorization: Bearer rg_live_…

Getting a key

1. Log in and open Account.
2. In the API keys card, give the key a name (for example Zapier) and click Create.
3. Copy the key straight away — it is shown once. We store only a hash, so a lost key can’t be recovered; revoke it and create a new one.

API keys are available on the Pro plan. If you don’t see the card, upgrade to Pro.

Example

List your reels:

curl https://reelguud-backend.guud.ai/api/reels \
  -H "Authorization: Bearer rg_live_YOUR_KEY"

Endpoints

All endpoints live under the API base URL https://reelguud-backend.guud.ai and require Authorization: Bearer rg_live_…. Responses are JSON. The typical flow is: upload media, wait for it to be tagged, then generate a reel.

• POST /api/upload — upload images and video clips
• POST /api/reels — generate a reel
• GET /api/reels — list your reels
• GET /api/reels/{id} — get one reel
• GET /api/reels/{id}/download — download a reel’s MP4

curl -X POST https://reelguud-backend.guud.ai/api/upload \
  -H "Authorization: Bearer rg_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

{
  "items": [
    {
      "asset_id": 4821,
      "external_id": "6f1c2e0a-…",
      "owner_user_id": 312,
      "asset_type": "image",
      "mime_type": "image/jpeg",
      "file_name": "beach.jpg",
      "file_extension": "jpg",
      "file_size_bytes": 1843200,
      "url": "https://reelguud-backend.guud.ai/uploads/1727790000000-9c1e4f2ab3d07e65.jpg",
      "thumbnail_url": "",
      "title": "beach.jpg",
      "tags_json": null,
      "processing_status": "uploading",
      "created_at": "2026-10-01T14:05:12.000Z",
      "updated_at": "2026-10-01T14:05:12.000Z"
    }
  ],
  "count": 1
}

curl -X POST https://reelguud-backend.guud.ai/api/reels \
  -H "Authorization: Bearer rg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Summer road trip","theme":"summer road trip","preset":"reels"}'

{
  "reel_job_id": 1907,
  "user_id": 312,
  "title": "Summer road trip",
  "theme": "summer road trip",
  "preset": "reels",
  "keywords_json": null,
  "source_asset_ids_json": null,
  "output_url": "",
  "duration_ms": null,
  "status": "pending",
  "error_message": "",
  "music_enabled": 1,
  "template_id": null,
  "created_at": "2026-10-01T14:06:40.000Z",
  "updated_at": "2026-10-01T14:06:40.000Z"
}

curl "https://reelguud-backend.guud.ai/api/reels?status=ready&page=1&limit=20" \
  -H "Authorization: Bearer rg_live_YOUR_KEY"

{
  "items": [
    {
      "reel_job_id": 1907,
      "user_id": 312,
      "title": "Summer road trip",
      "theme": "summer road trip",
      "preset": "reels",
      "output_url": "https://reelguud-backend.guud.ai/uploads/reels/reel-1907.mp4",
      "duration_ms": 24000,
      "status": "ready",
      "error_message": "",
      "music_enabled": 1,
      "posted_url": null,
      "view_count": 3,
      "download_count": 1,
      "posted": false,
      "created_at": "2026-10-01T14:06:40.000Z",
      "updated_at": "2026-10-01T14:08:02.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

curl https://reelguud-backend.guud.ai/api/reels/1907 \
  -H "Authorization: Bearer rg_live_YOUR_KEY"

{
  "reel_job_id": 1907,
  "user_id": 312,
  "title": "Summer road trip",
  "theme": "summer road trip",
  "preset": "reels",
  "output_url": "https://reelguud-backend.guud.ai/uploads/reels/reel-1907.mp4",
  "duration_ms": 24000,
  "status": "ready",
  "error_message": "",
  "music_enabled": 1,
  "posted_url": null,
  "posted": false,
  "created_at": "2026-10-01T14:06:40.000Z",
  "updated_at": "2026-10-01T14:08:02.000Z"
}

curl -L https://reelguud-backend.guud.ai/api/reels/1907/download \
  -H "Authorization: Bearer rg_live_YOUR_KEY" \
  -o summer-road-trip.mp4

HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="Summer-road-trip.mp4"

<MP4 bytes>

Webhooks

Instead of polling, ReelGuud can call your server when a reel finishes. Set an https:// URL in the Webhook card on Account. Saving the URL shows a signing secret that starts with whsec_; keep it on your server. Saving again creates a new secret, and the old one stops working.

reel.ready

Sent once when a reel you generated changes to status: "ready". ReelGuud sends a POST to your URL with a JSON body:

{
  "event": "reel.ready",
  "id": 1907,
  "title": "Summer road trip",
  "output_url": "https://reelguud-backend.guud.ai/uploads/reels/reel-1907.mp4",
  "thumbnail_url": ""
}

It is shown formatted here; the actual body is sent as compact JSON on a single line.

Request headers

POST /your/webhook/path HTTP/1.1
Content-Type: application/json
User-Agent: ReelGuud-Webhooks/1
X-ReelGuud-Signature: 5d41402abc4b2a76b9719d911017c592a0f6b3e1c4d7e8f9a0b1c2d3e4f5a6b7

Delivery and retries

• Reply with any 2xx status within 10 seconds to accept the event.
• Any other status, a timeout or a network error counts as failed. ReelGuud tries up to 3 times in total, waiting a little longer before each retry.
• Redirects are not followed. A 3xx counts as failed, so use your final URL.
• Retries send the same body and the same signature. The same event can arrive more than once, so ignore an id you have already handled.

Verifying the signature

Every request includes an X-ReelGuud-Signature header. Check it before you trust the body; it proves the request came from ReelGuud and wasn’t changed.

1. Header: read X-ReelGuud-Signature. It is a 64-character lowercase hex string.
2. Signed payload: the raw request body, byte for byte as you received it. Don’t parse the JSON and serialize it again first: changes to key order or spacing change the digest. No timestamp or other prefix is added.
3. Digest: compute HMAC-SHA256 of that raw body, keyed with your full webhook secret (including the whsec_ prefix, as UTF-8), and hex-encode it.
4. Compare: compare your hex digest with the header value using a constant-time comparison. If they don’t match, reply 401 and ignore the request.

Node.js (Express)

const crypto = require('crypto');
const express = require('express');
const app = express();

const SECRET = process.env.REELGUUD_WEBHOOK_SECRET; // whsec_…

// express.raw keeps the exact bytes that were signed.
app.post('/webhooks/reelguud', express.raw({ type: 'application/json' }), (req, res) => {
  const received = req.get('X-ReelGuud-Signature') || '';
  const expected = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const ok = received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.status(401).send('bad signature');

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.event === 'reel.ready') {
    console.log(`Reel ${event.id} is ready: ${event.output_url}`);
  }
  res.sendStatus(200);
});

Python

import hashlib, hmac

def is_valid_reelguud_signature(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

Check a signature by hand

Save a request body to body.json and compare the output with the header:

openssl dgst -sha256 -hmac "whsec_YOUR_SECRET" -hex < body.json