Contentdrips API Documentation

Read documentation of our API that generates social media carousels & graphics

Authentication

All endpoints require Bearer token authentication.
Authorization: Bearer {'{your_token}'} Content-Type: application/json

Overview

This API provides asynchronous image/PDF generation from templates. The workflow consists of:
  1. Submit Job → Get job ID
  2. Check Status → Poll until complete
  3. Get Result → Download generated files

Endpoints

Method Endpoint Description
POST /render Submit single graphic job
POST /render?tool=carousel-maker Submit carousel job
GET /job/:jobId/status Check job status
GET /job/:jobId/result Get completed result
GET /queue/stats Get queue statistics (no auth required)

Single Post Graphic Generation

1. Submit Job

Endpoint

POST /render

Example Request

const response = await fetch("https://generate.contentdrips.com/render", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN_HERE"
  },
  body: JSON.stringify({
    template_id: "123456",
    output: "png", // or "pdf"
    content_update: [
      {
        type: "textbox",
        label: "quote",
        value: "Your inspiring quote goes here",
        fontSize: "48",
        fontColor: "#333333",
        textboxMaxHeight: 300
    },
    {
        "type":"image",
        "label":"background",
        "value": "https://example.com/image.jpg",
        "opacity":0.8
    }

Content Updates Properties - Text

Property Type Required Description Example
type String Yes Must be "textbox" "textbox"
label String Yes Matches template element's meta_labels "heading"
value String Yes Text content "Hello World"
fontSize String/Number No Font size in pixels "48" or 48
fontColor String No Text color (CSS format) "#FF5733", "rgb(255,87,51)"
textboxMaxHeight String/Number No Max height: "auto" or integer "auto" or 250

Content Updates Properties - Image

Property Type Required Description Example
type String Yes Must be "image" "image"
label String Yes Matches template element's meta_labels "background"
value String Yes Image URL "https://..."
opacity Number No Image transparency (0–1) 0.8

Success Response (202 Accepted)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "message": "Job has been queued for processing",
  "check_status_url": "/job/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status"
}

2. Check Job Status

Endpoint

GET /job/:jobId/status

Response Examples (Status: Completed)

{
  "job_id": "...",
  "status": "completed",
  "updated_at": "2024-01-15T10:35:00.000Z",
  "completedAt": "2024-01-15T10:35:00.000Z"
}

Response Examples (Status: Failed)

{
  "job_id": "...",
  "status": "failed",
  "error": "Template not found"
}

3. Get Job Result

Endpoint

GET /job/:jobId/result

Success Response - PNG Output

{
  "date": "2024-01-15T10:35:00.000Z",
  "type": "normal",
  "export_url": "https://your-bucket.s3.amazonaws.com/server/.../abc123-template.png"
}

Job Not Ready Response

{
  "job_id": "...",
  "status": "processing",
  "message": "Job not yet completed"
}

Complete Workflow Example - Single Graphic

// ... (The full JavaScript example for single graphic workflow) ...
async function generateSingleGraphic() {
  // Step 1: Submit job
  // ...
  // Step 2: Poll status until complete
  // ...
  // Step 3: Get result
  // ...
}

generateSingleGraphic();

Carousel Generation

1. Submit Carousel Job

Endpoint

POST /render?tool=carousel-maker

(Basic Format) Example Request Structure

The carousel object must contain intro_slide, slides array, and ending_slide. 
// ... headers and auth ...
  body: JSON.stringify({
    template_id: "126149",
    output: "png",
    carousel: {
      intro_slide: { /* ... */ },
      slides: [ /* ... */ ],
      ending_slide: { /* ... */ }
    }
  })
// ...

Heading/Description (Basic Format)

Property Type Description
heading String Heading text
description String Description text
image String Image URL

(New Advanced Format) Example Request Structure

The carousel object must contain intro_slide, slides array, and ending_slide. 
// ... headers and auth ...
  body: JSON.stringify({
    template_id: "126149",
    output: "png",
    {
      "carousel": {
        "intro_slide": {
          "heading": {
            "text": "Welcome to Our Platform",
            "fontSize": "56",
            "fontColor": "#2C3E50",
            "textboxMaxHeight": "auto"
          },
          "description": {
            "text": "Discover amazing features",
            "fontSize": "28",
            "fontColor": "#7F8C8D",
            "textboxMaxHeight": 200
          },
          "image": {
            "url": "https://example.com/intro.jpg",
            "opacity": 0.85
          }
        },
        "slides": [
          {
            "heading": {
              "text": "Feature 1",
              "fontSize": "48",
              "fontColor": "#3498DB",
              "textboxMaxHeight": 180
            },
            "description": {
              "text": "Powerful features",
              "fontSize": "22",
              "fontColor": "#34495E",
              "textboxMaxHeight": "auto"
            },
            "image": {
              "url": "https://example.com/feature3.jpg",
              "opacity": 1
            }
          }
        ],
        "ending_slide": {
          "heading": {
            "text": "Get Started Today!",
            "fontSize": "60",
            "fontColor": "#E74C3C",
            "textboxMaxHeight": 250
          },
          "description": {
            "text": "Join thousands of users",
            "fontSize": "24",
            "fontColor": "#95A5A6"
          },
          "image": {
            "url": "https://example.com/ending.jpg",
            "opacity": 0.9
          }
        }
      }
    }
  })
// ...

Heading/Description (Advanced Format)

Property Type Required Description Example
text String Yes Text content "Welcome"
fontSize String/Number No Font size in pixels "48" or 48
fontColor String No Text color (CSS format) "#FF5733"
textboxMaxHeight String/Number No Max height "auto" or 250

Images (Advanced Format)

Property Type Required Description Example
url String Yes Image URL "https://..."
opacity Number No Image transparency (0–1) 0.8

Success Response (202 Accepted)

{
  "job_id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
  "status": "queued",
  "message": "Job has been queued for processing"
}

2. Check Carousel Job Status

Same as single graphic job status check (GET /job/:jobId/status).

3. Get Carousel Result

Success Response - PNG Output (Multiple Images)

{
  "date": "...",
  "type": "carousel", 
  "export_url": [
    "https://your-bucket.s3.amazonaws.com/.../frame-0.png",
    "https://your-bucket.s3.amazonaws.com/.../frame-1.png",
    // ... more URLs
  ]
}

Success Response - PDF Output (Single PDF)

{
  "date": "...",
  "type": "carousel",
  "export_url": "https://your-bucket.s3.amazonaws.com/.../carousel-output.pdf"
}

Complete Workflow Example - Carousel

// ... (The full JavaScript example for carousel workflow) ...
async function generateCarousel() {
  // Step 1: Submit carousel job
  // ...
  // Step 2: Poll status until complete
  // ...
  // Step 3: Get result
  // ...
}

generateCarousel();

Request Parameters Reference

Required Parameters

  • template_id (String): Unique identifier for the template to use.

Optional Parameters

  • output (String, Default: "png"): Output format. Values: "png" | "pdf".
  • branding (Object): User branding information (name, handle, avatar_image_url, etc.).
  • content_update (Array): For single graphic templates. Array of { type, label, value } objects.
  • carousel (Object): For carousel templates (required when using ?tool=carousel-maker). Contains intro_slide, slides array, and ending_slide.

Error Responses

HTTP Status Codes

Code Description
202 Accepted (job queued successfully)
400 Bad Request (validation error)
401 Unauthorized (invalid/missing token)
404 Not Found (job/template not found)
500 Internal Server Error

Error Response Format

{
  "error": "Error Type",
  "message": "Detailed error description"
}

Queue Statistics

Get Queue Stats

Endpoint (No Auth Required)

GET /queue/stats

Response Example

{
  "waiting": 5,
  "active": 2,
  "completed": 1543,
  "failed": 12
  // ... other stats
}

Tips & Best Practices

  • **Polling Recommendations:** Poll status every **5 seconds** and set a maximum timeout.
  • **Template Labels:** Content update labels must match the template's `meta_labels`.
  • **Output Formats:** **PNG** for social media images, **PDF** for presentations/printables.
  • **Error Handling:** Always check the response status code and store job IDs.

Support

For additional support or questions about the API, please contact the development team.

Contentdrips

  • Write, design & repurpose content to grow your personal brand

PAGES

OUR PRODUCTS

Stay In Touch

FEATURES

COMPARE

FREE TOOLS

Contentdrips API

USE CASES

API COMPARE