Quickstart

By the end of this guide you’ll have made your first authenticated render against the Kynva API and have a URL to the finished PNG.

You’ll need a terminal and either curl, Node 18+, or Python 3.9+.

Create an account

Go to www.kynva.ai/sign-up and sign up. The free tier includes 50 renders/month to try the API.

Create an API key

Open Settings → API Keys and click Create key. Pick a descriptive name like quickstart-local.You’ll see a one-time secret that looks like:

kyn_live_abc123def456...

Copy it now — you won’t be able to see it again. Treat it like a password.

Export it as an env var

export KYNVA_API_KEY="kyn_live_..."

$env:KYNVA_API_KEY = "kyn_live_..."

2. Make your first render

Everything in Kynva flows through one endpoint: POST /api/v1/facade/generate. You send a RenderForgeRequestV1 — your content, a brand kit, and an export target — and with "operation": "preview" the response comes back synchronously with the rendered output.

curl -X POST "https://api.kynva.ai/api/v1/facade/generate" \
  -H "Authorization: Bearer $KYNVA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2026-01-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "spec_type": "renderforge_request",
    "spec_version": "1.0",
    "operation": "preview",
    "generation_type": "image",
    "intent": {
      "identity": {
        "request_id": "quickstart-001",
        "brand_id": "default",
        "source": "direct_api"
      },
      "content": {
        "spec_type": "content",
        "spec_version": "1.0",
        "headline": "Summer Sale",
        "subhead": "Everything 30% off",
        "cta": "Shop now"
      },
      "assets": { "spec_type": "assets", "spec_version": "1.0" },
      "brand_kit": {
        "spec_type": "brand_kit",
        "spec_version": "1.0",
        "brand_id": "default",
        "kit_version": "1.0",
        "status": "active",
        "fonts": [{ "family": "Inter", "weights": [400, 600, 700] }],
        "colors": { "bg": "#ffffff", "text": "#1a1a1a", "accent": "#2563eb" },
        "logos": { "light": "", "dark": "" },
        "safe_profiles": {},
        "policies": {}
      },
      "style_brief": {
        "spec_type": "style_brief",
        "spec_version": "1.0",
        "mode": "auto",
        "tone": ["bold", "vibrant"]
      },
      "export_intent": {
        "spec_type": "export_intent",
        "spec_version": "1.0",
        "primary": {
          "platform": "instagram",
          "format": "png",
          "profile_id": "ig_square_1x1"
        }
      }
    },
    "execution": {
      "execution_mode": "preview",
      "seed": 42,
      "quality_floor": 70
    }
  }'

// npm install @kynva/sdk
import { KynvaClient } from "@kynva/sdk";

const kynva = new KynvaClient({ apiKey: process.env.KYNVA_API_KEY! });

const res = await kynva.generate({
  spec_type: "renderforge_request",
  spec_version: "1.0",
  operation: "preview",
  generation_type: "image",
  intent: {
    identity: { request_id: crypto.randomUUID(), brand_id: "default", source: "direct_api" },
    content: {
      spec_type: "content", spec_version: "1.0",
      headline: "Summer Sale", subhead: "Everything 30% off", cta: "Shop now",
    },
    assets: { spec_type: "assets", spec_version: "1.0" },
    brand_kit: {
      spec_type: "brand_kit", spec_version: "1.0",
      brand_id: "default", kit_version: "1.0", status: "active",
      fonts: [{ family: "Inter", weights: [400, 600, 700] }],
      colors: { bg: "#ffffff", text: "#1a1a1a", accent: "#2563eb" },
      logos: { light: "", dark: "" }, safe_profiles: {}, policies: {},
    },
    style_brief: { spec_type: "style_brief", spec_version: "1.0", mode: "auto", tone: ["bold", "vibrant"] },
    export_intent: {
      spec_type: "export_intent", spec_version: "1.0",
      primary: { platform: "instagram", format: "png", profile_id: "ig_square_1x1" },
    },
  } as never,
  execution: { execution_mode: "preview", seed: 42, quality_floor: 70 },
});

console.log(res.outputs?.[0]?.url); // → https://cdn…/….png

import json, os, uuid, urllib.request

request = {
    "spec_type": "renderforge_request",
    "spec_version": "1.0",
    "operation": "preview",
    "generation_type": "image",
    "intent": {
        "identity": {"request_id": str(uuid.uuid4()), "brand_id": "default", "source": "direct_api"},
        "content": {
            "spec_type": "content", "spec_version": "1.0",
            "headline": "Summer Sale", "subhead": "Everything 30% off", "cta": "Shop now",
        },
        "assets": {"spec_type": "assets", "spec_version": "1.0"},
        "brand_kit": {
            "spec_type": "brand_kit", "spec_version": "1.0",
            "brand_id": "default", "kit_version": "1.0", "status": "active",
            "fonts": [{"family": "Inter", "weights": [400, 600, 700]}],
            "colors": {"bg": "#ffffff", "text": "#1a1a1a", "accent": "#2563eb"},
            "logos": {"light": "", "dark": ""}, "safe_profiles": {}, "policies": {},
        },
        "style_brief": {"spec_type": "style_brief", "spec_version": "1.0", "mode": "auto", "tone": ["bold", "vibrant"]},
        "export_intent": {
            "spec_type": "export_intent", "spec_version": "1.0",
            "primary": {"platform": "instagram", "format": "png", "profile_id": "ig_square_1x1"},
        },
    },
    "execution": {"execution_mode": "preview", "seed": 42, "quality_floor": 70},
}

req = urllib.request.Request(
    "https://api.kynva.ai/api/v1/facade/generate",
    data=json.dumps(request).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['KYNVA_API_KEY']}",
        "Content-Type": "application/json",
        "X-API-Version": "2026-01-01",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
with urllib.request.urlopen(req) as resp:
    body = json.load(resp)
print(body["outputs"][0]["url"])

The response includes an outputs array — each entry has the rendered image’s url, dimensions, and format:

{
  "spec_type": "renderforge_response",
  "status": "ok",
  "outputs": [
    {
      "profile_id": "ig_square_1x1",
      "format": "png",
      "platform": "instagram",
      "url": "https://cdn.kynva.ai/previews/prv-…/ig_square_1x1.png",
      "width": 1080,
      "height": 1080
    }
  ]
}

Open the URL — that’s your design.

3. Run it again — get the same bytes

Run the exact same request a second time. The output is byte-identical — same layout, same pixels. That’s the determinism contract: same request + seed → same design, forever. Change "seed": 42 to another number for a different (but equally reproducible) layout take.

Where to go next

Render with your real brand

Build a brand kit from your website with one call, then render on-brand.

Async render jobs

Queue renders, poll status, or get webhooks — for pipelines and batches.

Signed image URLs

The OG-image primitive: URLs that render on first fetch, cached forever.

Webhooks

render.completed / render.failed with HMAC-signed deliveries.

Get started

Core concepts

Guides

Errors

Changelog

2. Make your first render

3. Run it again — get the same bytes

Where to go next

Render with your real brand

Async render jobs

Signed image URLs

Webhooks

​1. Sign up and grab an API key

​2. Make your first render

​3. Run it again — get the same bytes

​Where to go next

Render with your real brand

Async render jobs

Signed image URLs

Webhooks

1. Sign up and grab an API key

2. Make your first render

3. Run it again — get the same bytes

Where to go next