Contentdrips API Documentation

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

Base URL

https://generate.contentdrips.com

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"
      }
      /* ... other content ... */
    ]
  })
});

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

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: { /* ... */ }
    }
  })
// ...

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