Pablle Image Generation API

Overview

The /api/generate-graphic endpoint allows users to generate graphics from templates with specific layer modifications. This endpoint leverages the existing createDesign tool logic to merge user modifications with template data.

Endpoint Details

Request Format

Headers

Authorization: Bearer <jwt_token>
Content-Type: application/json (required for POST, optional for GET)

POST Request (JSON Body)

The POST method accepts a JSON body with the request parameters:

Request Body

{
  templateId: string,        // Required: UUID of the template to use
  pageIndex: number,         // Required: 0-based index of the page to modify
  modifiedLayers: Array<{   // Required: Array of layer modifications
    id: string,             // Required: Layer ID to identify which layer to modify
    // Optional: Any layer properties to update (text, color, position, etc.)
    // Only fields that should be updated need to be included
  }>,
  name?: string,            // Optional: Name for the generated design
  scale?: number           // Optional: Scale factor for output dimensions (1 = original, 2 = double, etc.)
}

Example Request

{
    "templateId": "123e4567-e89b-12d3-a456-426614174000",
    "pageIndex": 0,
    "modifiedLayers": [
        {
            "id": "text-layer-1",
            "text": "Updated text content",
            "color": "#FF0000",
            "fontSize": 24
        },
        {
            "id": "rectangle-layer-2",
            "backgroundColor": "#00FF00",
            "borderRadius": 10
        }
    ],
    "name": "My Custom Graphic",
    "scale": 2
}

Response Format

Success Response (200)

{
  success: true,
  designId: string,        // ID of the created design
  previewUrl?: string,    // Generated preview URL if available
  message: string         // Success message
}

Error Response (400/401/404/500)

{
  success: false,
  error: string,          // Error message
  details?: any          // Additional error details (for validation errors)
}

GET Request (Query Parameters)

For GET requests, parameters are passed as URL query parameters:

GET /api/generate-graphic?
  templateId={uuid}&
  pageIndex={number}&
  name={string}&
  scale={number}&
  modifiedLayers={json_array_as_string}

Query Parameters

• templateId (required): UUID of the template to use
• pageIndex (required): 0-based index of the page to modify (as integer)
• name (optional): Name for the generated design
• scale (optional): Scale factor as number
• modifiedLayers (required): JSON-encoded array string containing layer modifications

Understanding the modifiedLayers Parameter

For GET requests, the modifiedLayers parameter must be a JSON-encoded array string passed as a query parameter.

Step 1: Create your JSON array

[
    {
        "id": "layer-id",
        "text": "New content",
        "color": "#FF0000",
        "fontSize": 24
    }
]

Step 2: Convert to URL-encoded string

The same JSON array in URL-encoded format:

modifiedLayers=[{%22id%22:%22layer-id%22,%22text%22:%22New%20content%22,%22color%22:%22%23FF0000%22}]

GET Request Example

curl "http://localhost:3000/api/generate-graphic?templateId=0247df86-c859-47e7-8db4-b82e9e49557e&pageIndex=0&name=Hello+World+Graphic&modifiedLayers=[{"id":"text-layer-1","text":"Hello+World!","color":"%23FF0000"}]" \
    -H "Authorization: Bearer <your_jwt_token>"

Note: Most HTTP clients will handle URL encoding automatically. When manually constructing URLs, ensure the JSON array is properly URL-encoded.

Usage Examples

Basic Text Modification (POST)

curl -X POST http://localhost:3000/api/generate-graphic \
    -H "Authorization: Bearer <your_jwt_token>" \
    -H "Content-Type: application/json" \
    -d '{
    "templateId": "0247df86-c859-47e7-8db4-b82e9e49557e",
    "pageIndex": 0,
    "modifiedLayers": [
      {
        "id": "text-layer-1",
        "text": "Hello World!",
        "color": "#FF0000"
      }
    ],
    "name": "Hello World Graphic"
  }'

Multiple Layer Modifications

curl -X POST http://localhost:3000/api/generate-graphic \
    -H "Authorization: Bearer <your_jwt_token>" \
    -H "Content-Type: application/json" \
    -d '{
    "templateId": "0247df86-c859-47e7-8db4-b82e9e49557e",
    "pageIndex": 0,
    "modifiedLayers": [
      {
        "id": "text-layer-1",
        "text": "Updated Title",
        "fontSize": 32,
        "color": "#0000FF"
      },
      {
        "id": "rectangle-layer-2",
        "backgroundColor": "#FFFF00",
        "borderRadius": 15
      },
      {
        "id": "image-layer-3",
        "backgroundImageUrl": "https://example.com/new-image.jpg"
      }
    ],
    "name": "Multi-layer Modified Graphic"
  }'

Scaled Output (2x Size)

curl -X POST http://localhost:3000/api/generate-graphic \
    -H "Authorization: Bearer <your_jwt_token>" \
    -H "Content-Type: application/json" \
    -d '{
    "templateId": "0247df86-c859-47e7-8db4-b82e9e49557e",
    "pageIndex": 0,
    "modifiedLayers": [
      {
        "id": "text-layer-1",
        "text": "Scaled Text",
        "color": "#FF0000"
      }
    ],
    "name": "Scaled Graphic",
    "scale": 2
  }'

Scaling Behavior

When a scale factor is provided:

• Page Dimensions: Width and height are multiplied by the scale factor
• Layer Dimensions: All layer widths and heights are scaled
• Layer Positions: X and Y coordinates are scaled proportionally
• Text Properties: Font size and line height are scaled
• Border Radius: Border radius values are scaled
• Scale = 1: No scaling applied (original dimensions)
• Scale = 2: Double size (2x dimensions)
• Scale = 0.5: Half size (0.5x dimensions)

Validation

• Authentication: Bearer token validation
• Template ID: UUID format validation
• Page Index: Non-negative integer validation
• Layer IDs: Existence validation against template layers
• Layer Modifications: At least one modification required
• Scale Factor: Must be a positive number (optional, defaults to 1)

Error Handling

• 401: Missing or invalid Authorization header
• 400: Invalid request data or validation errors
• 404: Template not found or inaccessible
• 500: Database errors or internal server errors

Security Considerations

• Bearer token authentication required
• User can only access their own templates
• Template ownership validation before processing
• Layer modification sanitization to prevent injection

Testing

A test endpoint is available at /api/test-generate-graphic (GET) that:

• Examines template structure
• Tests layer merging logic
• Validates request schema
• Provides sample data for testing