Agent Integration Guide

Two Modes

Standard Slots

Every template accepts these universal slots. Use consistent names across all templates for automation (CSV imports, batch generation).

Category-Specific Slots

Slot Aliases

The renderer auto-resolves these alternative names, so both conventions work:

Recommended Agent Workflow

Template Categories

Browse templates by category using GET /api/v1/templates?category=... or see all categories at GET /api/v1/templates/categories

Infographic Decision Tree

When the user wants an infographic, pick the right template based on intent. All infographic templates use Direct Render. No photo needed.

OpenAI Function Definition

{
  "name": "generate_infographic",
  "description": "Generate an infographic image (flowchart, checklist, comparison, or timeline)",
  "parameters": {
    "type": "object",
    "properties": {
      "templateId": {
        "type": "string",
        "enum": ["flowchart", "process-horizontal", "checklist", "comparison-vs", "timeline-vertical"]
      },
      "slots": {
        "type": "object",
        "description": "Template-specific content and color slots"
      },
      "size": {
        "type": "string",
        "enum": ["1080x1080", "1200x628", "1080x1920", "1200x1200", "1280x720"],
        "default": "1080x1080"
      },
      "logoUrl": {
        "type": "string",
        "description": "HTTPS URL to a logo image. PNG with transparent background recommended. Placed as overlay on the generated image."
      },
      "logoPosition": {
        "type": "string",
        "enum": ["top-left", "top-right", "bottom-left", "bottom-right"],
        "description": "Where to place the logo on the image. Default: bottom-left."
      }
    },
    "required": ["templateId", "slots"]
  }
}

Quick Start — Direct Render

GET https://api.rendrkit.dev/api/v1/templates?category=food

// Or browse all categories:
GET https://api.rendrkit.dev/api/v1/templates/categories

// Filter by style:
GET https://api.rendrkit.dev/api/v1/templates?category=food&style=photo

// Search:
GET https://api.rendrkit.dev/api/v1/templates?search=restaurant

POST https://api.rendrkit.dev/api/v1/generate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "templateId": "dish-spotlight",
  "slots": {
    "heading": "Truffle Risotto",
    "subheading": "Creamy arborio rice with black truffle shavings",
    "badge_text": "CHEF'S SPECIAL",
    "price": "$28",
    "accent_color": "#D4A574"
  }
}

{
  "id": "abc-123",
  "url": "https://storage.rendrkit.dev/images/abc-123.png",
  "width": 1080,
  "height": 1080,
  "templateId": "dish-spotlight"
}

Best Practices for High-Quality Images

1. Use Direct Render (recommended)

Direct render gives you full control and the best quality. Your agent picks the template and fills every slot.

2. Always Fill These Slots

3. Choose the Right Template Type

4. Photo Query Tips

5. Template Selection Workflow

1. GET /api/v1/templates?category=food → browse food templates
2. Pick "dish-spotlight" → check its slots
3. POST /generate with templateId + all slots filled
4. Return image to user

Quick Start per Template

Copy-paste these curl commands to generate images instantly. Replace YOUR_API_KEY with your key.

curl -X POST https://api.rendrkit.dev/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"tweet-card","slots":{"avatar_letter":"A","display_name":"Alex Rivera","handle":"@alexr","tweet_text":"Just shipped the biggest update of the year.","likes":"2.4K","retweets":"312","accent_color":"#1D9BF0"}}'

curl -X POST https://api.rendrkit.dev/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"gradient-hero","slots":{"heading":"The Future is Now","subheading":"AI-powered analytics that understand your business","badge_text":"NOW IN BETA","accent_color":"#8B5CF6","cta_text":"Join Waitlist"}}'

curl -X POST https://api.rendrkit.dev/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"magazine-cover","slots":{"heading":"Taste Tuscany","subheading":"Handmade pasta and wood-fired pizza","badge_text":"GRAND OPENING","accent_color":"#D4A574","cta_text":"Reserve a Table"}}'

curl -X POST https://api.rendrkit.dev/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"flash-sale","slots":{"badge_text":"FLASH SALE","heading":"24 Hours Only","discount":"70% OFF","accent_color":"#FF3B30","subheading":"Our biggest discount ever","cta_text":"Grab the Deal"}}'

curl -X POST https://api.rendrkit.dev/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"dish-spotlight","slots":{"heading":"Truffle Risotto","subheading":"Creamy arborio rice with black truffle shavings","badge_text":"CHEF\'S SPECIAL","price":"$28","accent_color":"#D4A574"}}'

Common Mistakes

Custom Fonts

Pass a Google Fonts name to use custom typography in generated images. Falls back to the template's default font if the name is invalid.

{ "templateId": "gradient-hero", "slots": {...}, "font": "Poppins" }

{ "templateId": "...", "slots": {...}, "brand": { "font": "Montserrat", "colors": ["#FF0000"] } }

Supported: any Google Fonts name (e.g. "Poppins", "Playfair Display", "Roboto", "Montserrat").

Logo Overlay

Add your brand logo to any generated image. Pass it as a top-level parameter (not inside slots).

Example

curl -X POST https://api.rendrkit.dev/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "dark-overlay",
    "size": "1080x1080",
    "logoUrl": "https://example.com/logo.png",
    "logoPosition": "bottom-left",
    "slots": {
      "heading": "Summer Collection",
      "subheading": "New arrivals now available",
      "cta_text": "Shop Now"
    }
  }'

A/B Variants

Generate 2-3 color variations of the same design for A/B testing. Each variant uses a different accent color (hue-shifted) while keeping the same content. Each variant counts as 1 image toward your quota.

curl -X POST https://api.rendrkit.dev/api/v1/generate \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "flash-sale",
    "slots": {
      "heading": "Summer Sale",
      "subheading": "50% off everything",
      "cta_text": "Shop Now",
      "accent_color": "#DC2626"
    },
    "variants": 3
  }'

Returns an array of images, each with a variant number:

{
  "images": [
    { "id": "...", "url": "...", "variant": 1 },
    { "id": "...", "url": "...", "variant": 2 },
    { "id": "...", "url": "...", "variant": 3 }
  ]
}

Photo Guidelines

Content Tips for 9/10 Quality

OpenAI Function Calling

list_templates

{
  "name": "list_templates",
  "description": "Browse available image templates by category. Call this first to find the right template.",
  "parameters": {
    "type": "object",
    "properties": {
      "category": {
        "type": "string",
        "enum": ["social", "marketing", "business", "food", "lifestyle", "events", "education", "tech", "creative"],
        "description": "Filter by category"
      },
      "style": {
        "type": "string",
        "description": "Filter by style tag: photo, gradient, dark, light, minimal, bold, elegant, neon"
      }
    }
  }
}

generate_image

{
  "name": "generate_image",
  "description": "Generate a professional image using RendrKit. First call list_templates to find the right template, then generate.",
  "parameters": {
    "type": "object",
    "properties": {
      "templateId": {
        "type": "string",
        "description": "Template ID from list_templates. Use direct render for best results."
      },
      "slots": {
        "type": "object",
        "description": "Template content slots. Key slots: heading (required, 2-4 words), subheading (one sentence), badge_text (1-2 word label like NEW/SALE), details (date/location/price), photoQuery (1-3 word Unsplash search), cta_text (only if user wants a button). Check GET /templates for template-specific slots.",
        "additionalProperties": { "type": "string" }
      },
      "prompt": {
        "type": "string",
        "description": "Fallback: describe the image and AI picks the template. Less control than direct render."
      },
      "imageUrl": {
        "type": "string",
        "description": "Optional: your own photo URL to use as background"
      },
      "size": {
        "type": "string",
        "enum": ["1080x1080", "1200x628", "1080x1920", "1200x1200"],
        "description": "Image dimensions. Default: 1080x1080"
      },
      "logoUrl": {
        "type": "string",
        "description": "HTTPS URL to a logo image. PNG with transparent background recommended. Placed as overlay on the generated image."
      },
      "logoPosition": {
        "type": "string",
        "enum": ["top-left", "top-right", "bottom-left", "bottom-right"],
        "description": "Where to place the logo on the image. Default: bottom-left."
      }
    }
  }
}

Full Examples

{
  "templateId": "magazine-cover",
  "slots": {
    "heading": "Taste Tuscany",
    "subheading": "Handmade pasta, wood-fired pizza, local wines",
    "badge_text": "GRAND OPENING",
    "accent_color": "#D4A574"
  },
  "imageUrl": "https://example.com/restaurant-interior.jpg"
}

{
  "templateId": "stats-banner",
  "slots": {
    "heading": "2025 In Review",
    "subheading": "A record-breaking year",
    "stat1_number": "10M+",
    "stat1_label": "Users Served",
    "stat2_number": "99.9%",
    "stat2_label": "Uptime",
    "stat3_number": "150+",
    "stat3_label": "Countries",
    "accent_color": "#3B82F6"
  }
}

{
  "templateId": "gradient-hero",
  "slots": {
    "heading": "Ship Faster",
    "subheading": "The deployment platform that gets out of your way",
    "badge_text": "NOW IN BETA",
    "accent_color": "#8B5CF6",
    "cta_text": "Start Free"
  }
}

{
  "templateId": "announcement",
  "slots": {
    "bg_word": "NEW",
    "badge_text": "JUST LAUNCHED",
    "heading": "Version 3.0 is Here",
    "subheading": "Completely redesigned with 50+ new features",
    "cta_text": "See What's New",
    "accent_color": "#3B82F6"
  }
}

{
  "templateId": "profile-card",
  "slots": {
    "name": "Alex Rivera",
    "role": "Head of Product",
    "bio": "Building products that people love. Previously at Stripe and Figma.",
    "link1_text": "LinkedIn",
    "link2_text": "Twitter",
    "accent_color": "#3B82F6"
  },
  "imageUrl": "https://example.com/headshot.jpg"
}

Rate Limits & Pricing