API Documentation

29 July 2024

Overview

The Pin Generator API lets you programmatically create Pinterest pin images, schedule them to your connected Pinterest profiles, or do both in a single request. All endpoints are authenticated using your access key, which you can find on your profile page.

Every API call consumes credits from your account, just like using the Pin Generator UI.

Base URL

https://europe-west3-pingenerator-43a15.cloudfunctions.net/highMemLimitApi

Authentication

All requests must include your access key as a header:

access_key: your_access_key_here

You can find your access key on your profile page under API access key. Keep this key secure and never expose it in public repositories or client-side code.

Endpoints

1. Generate Image

Generates a Pinterest pin image and returns the hosted image URL. The image is stored in your Pin Generator account and can be used later for scheduling or downloading.

POST /api/generateImage

Request Body (JSON)

Parameter	Type	Required	Description
`template`	string	Yes	Template ID, template name, or `"RandomTemplate"` to pick a random basic template. Template IDs can be found in the URL when editing a template on pingenerator.com. See template names below.
`title`	string	Yes	The title text displayed on the pin.
`imageURL`	string	No	URL of the image to use in the pin. Must be a publicly accessible image URL.
`url`	string	No	The destination URL the pin links to.
`urlText`	string	No	Display text for the URL shown on the pin (e.g. `yoursite.com`).
`color`	string	No	Hex color code for the pin (with or without `#`). Example: `"ae3ac4"` or `"#ae3ac4"`.
`description`	string	No	Description text for the pin.
`custom1`, `custom2`, `custom3`, …	string	No	Custom text fields that replace `{custom1}`, `{custom2}`, `{custom3}`, etc. placeholders in your template’s text layers. See Custom Fields below.

Example Request

curl -X POST 'https://europe-west3-pingenerator-43a15.cloudfunctions.net/highMemLimitApi/api/generateImage' \
  -H 'access_key: your_access_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "RandomTemplate",
    "title": "10 Best Beaches in Brazil",
    "imageURL": "https://example.com/beach-photo.jpg",
    "url": "https://yourblog.com/best-beaches-brazil",
    "urlText": "yourblog.com",
    "color": "ae3ac4",
    "description": "Discover the most beautiful beaches in Brazil",
    "custom1": "Sale ends Friday",
    "custom2": "20% off"
  }'

Success Response (200)

{
  "imageURL": "https://firebasestorage.googleapis.com/v0/b/.../image.jpeg?alt=media"
}

Credits

Each call consumes 1 image credit.

2. Generate Image & Schedule

Generates a pin image and schedules it to be posted to one of your connected Pinterest profiles. You can either specify an exact board to pin to, or let AI choose the best board automatically.

POST /api/generateAndSchedule

Request Body (JSON)

Parameter	Type	Required	Description
`template`	string	Yes	Template ID, template name, or `"RandomTemplate"`.
`title`	string	Yes	The title text displayed on the pin.
`pinterestProfile`	string	Yes	The username of your connected Pinterest profile (e.g. `"giftsforkevin"`).
`boardId`	string	Conditional	The Pinterest board ID to pin to. Required unless `useAIBoardSelection` is `true`. You can find board IDs in the board selector dropdown — hover over the copy icon next to any board name.
`imageURL`	string	No	URL of the image to use in the pin.
`url`	string	No	The destination URL the pin links to.
`urlText`	string	No	Display text for the URL on the pin.
`color`	string	No	Hex color code (with or without `#`).
`description`	string	No	Description text for the pin.
`boardSectionId`	string	No	Board section ID, if you want to pin to a specific section within the board. Section IDs can also be copied from the board selector dropdown.
`scheduledTime`	string	No	ISO 8601 date string for when to publish (e.g. `"2026-03-15T14:00:00.000Z"`). If omitted, the pin is added to your scheduling queue and posted according to your saved scheduling settings.
`useAIBoardSelection`	boolean	No	Set to `true` to let AI automatically select the best board based on the pin’s title and description. If no suitable board exists, AI will create a new one. When enabled, `boardId` is not required.
`custom1`, `custom2`, `custom3`, …	string	No	Custom text fields that replace `{custom1}`, `{custom2}`, `{custom3}`, etc. placeholders in your template’s text layers. See Custom Fields below.

Example Request — Manual Board

curl -X POST 'https://europe-west3-pingenerator-43a15.cloudfunctions.net/highMemLimitApi/api/generateAndSchedule' \
  -H 'access_key: your_access_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "RandomTemplate",
    "title": "10 Best Beaches in Brazil",
    "imageURL": "https://example.com/beach-photo.jpg",
    "url": "https://yourblog.com/best-beaches-brazil",
    "urlText": "yourblog.com",
    "color": "ae3ac4",
    "description": "Discover the most beautiful beaches in Brazil",
    "pinterestProfile": "your_pinterest_username",
    "boardId": "your_board_id",
    "boardSectionId": "optional_section_id",
    "scheduledTime": "2026-03-15T14:00:00.000Z"
  }'

Example Request — AI Board Selection

curl -X POST 'https://europe-west3-pingenerator-43a15.cloudfunctions.net/highMemLimitApi/api/generateAndSchedule' \
  -H 'access_key: your_access_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "RandomTemplate",
    "title": "10 Best Beaches in Brazil",
    "imageURL": "https://example.com/beach-photo.jpg",
    "url": "https://yourblog.com/best-beaches-brazil",
    "urlText": "yourblog.com",
    "color": "ae3ac4",
    "description": "Discover the most beautiful beaches in Brazil",
    "pinterestProfile": "your_pinterest_username",
    "useAIBoardSelection": true
  }'

Example Request — Queue Scheduling

Omit scheduledTime to add the pin to your scheduling queue. It will be posted according to the time slots you have configured in your scheduling settings on pingenerator.com.

curl -X POST 'https://europe-west3-pingenerator-43a15.cloudfunctions.net/highMemLimitApi/api/generateAndSchedule' \
  -H 'access_key: your_access_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "StandardTemplate",
    "title": "Best Hiking Trails in Patagonia",
    "imageURL": "https://example.com/patagonia.jpg",
    "url": "https://yourblog.com/patagonia-trails",
    "urlText": "yourblog.com",
    "color": "2d8f4e",
    "description": "Our favorite trails through Patagonia",
    "pinterestProfile": "your_pinterest_username",
    "boardId": "your_board_id"
  }'

Success Response (200)

{
  "message": "Pin generated and scheduled",
  "imageURL": "https://firebasestorage.googleapis.com/v0/b/.../image.jpeg?alt=media",
  "board": {
    "id": "992269799088633298",
    "name": "Travel Destinations"
  }
}

When a pin is added to the queue instead of scheduled for a specific date, the message will read "Pin generated and added to scheduling queue".

Credits

Each call consumes 1 image credit.

3. Schedule Existing Image

Schedules an already-generated image to Pinterest. Use this when you already have an image URL (for example, from a previous /api/generateImage call) and want to schedule it without generating a new image.

POST /api/schedulePin

Request Body (JSON)

Parameter	Type	Required	Description
`mediaURL`	string	Yes	The URL of the image to schedule. This can be an image URL returned from `/api/generateImage` or any publicly accessible image URL.
`pinterestProfile`	string	Yes	The username of your connected Pinterest profile.
`boardId`	string	Conditional	The Pinterest board ID. Required unless `useAIBoardSelection` is `true`.
`title`	string	No	Title for the pin on Pinterest.
`description`	string	No	Description for the pin on Pinterest.
`url`	string	No	The destination URL the pin links to.
`boardSectionId`	string	No	Board section ID for pinning to a specific section.
`scheduledTime`	string	No	ISO 8601 date string. If omitted, the pin is added to your scheduling queue.
`useAIBoardSelection`	boolean	No	Set to `true` to let AI pick the best board.

Example Request

curl -X POST 'https://europe-west3-pingenerator-43a15.cloudfunctions.net/highMemLimitApi/api/schedulePin' \
  -H 'access_key: your_access_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "mediaURL": "https://firebasestorage.googleapis.com/v0/b/.../image.jpeg?alt=media",
    "title": "10 Best Beaches in Brazil",
    "description": "Discover the most beautiful beaches in Brazil",
    "url": "https://yourblog.com/best-beaches-brazil",
    "pinterestProfile": "your_pinterest_username",
    "boardId": "your_board_id",
    "scheduledTime": "2026-03-15T14:00:00.000Z"
  }'

Success Response (200)

{
  "message": "Pin scheduled",
  "board": {
    "id": "992269799088633298",
    "name": "Travel Destinations"
  }
}

Credits

Each call consumes 1 image credit.

Error Responses

Status	Meaning	Example
`400`	Missing required parameter	`{"error": "template is required"}`
`401`	Invalid access key	`{"error": "User not found"}`
`402`	No credits remaining	`{"error": "Pin generation credits depleted"}`
`403`	Missing access key	`{"error": "Unauthorized"}`
`404`	Resource not found	`{"error": "Template not found"}` or `{"error": "Board not found or does not belong to this Pinterest profile"}`
`500`	Server error	`{"error": "Unable to generate image"}`

Template Reference

You can use any of the following built-in template names as the template parameter, or use "RandomTemplate" to pick one at random. You can also use the ID of any custom template you’ve created — find the ID in the URL when editing a template on pingenerator.com.

Template Name	Friendly Name	Style
`CenterWave`	Center wave	Wavey
`TextBlob`	Text blob	Wavey
`WaveySplit`	Wavey split	Wavey
`ColorBlobs`	Color blobs	Wavey
`SquareTextWithLandscapeImage`	Big text with landscape image	Square
`TextOverlay`	Text overlay	Square
`TextSideRight`	Text side right	Square
`BigTopText`	Big top text	Square
`StandardTemplate`	Standard	Standard
`LandscapeFriendly`	Landscape friendly	Standard
`FullImageWithBanner`	Full image with banner	Standard
`PortraitFriendly`	Portrait friendly	Standard
`ImageOnly`	Image only	Standard
`BlankWithFrame`	Image only with frame	Standard
`CircleImageWithBanner`	Circle image with banner	Standard

Custom Fields

Custom fields let you inject dynamic text into your pin designs via the API — the same way they work when uploading a CSV file in the Pin Generator UI.

How it works

In the Pin Generator template editor, set a text layer’s content to a placeholder such as {custom1}, {custom2}, or {custom3} (available from the “Use detected text” dropdown).
When calling the API, pass the corresponding field (e.g. "custom1": "Your text here") in the request body.
During image generation the placeholder is replaced with your text.

Supported fields

You can use custom1 through custom100. Field names are case-insensitive (Custom1 and custom1 are treated the same). Only the fields present in your request are applied — any placeholders without a matching field are left as-is.

Example

If your template contains a text layer with {custom1} and another with {custom2}:

{
  "template": "your_template_id",
  "title": "Summer Recipes",
  "custom1": "Ready in 15 minutes",
  "custom2": "Vegan friendly"
}

The generated image will display “Ready in 15 minutes” and “Vegan friendly” in the respective text layers.

Custom fields are available on the Generate Image and Generate Image & Schedule endpoints. They are not applicable to the Schedule Existing Image endpoint since no image rendering occurs.

Finding Board & Section IDs

Board IDs and section IDs can be found directly in the Pin Generator board selector dropdown. When you open the dropdown to select boards:

Hover over the copy icon next to any board name to see its ID in the tooltip.
Click the icon to copy the ID to your clipboard.
For board sections, expand a board first, then use the same copy icon next to the section name.

Scheduling Behavior

Specific Date

Provide a scheduledTime in ISO 8601 format (e.g. "2026-03-15T14:00:00.000Z") to schedule the pin for an exact date and time. The time is adjusted based on the timezone configured in your scheduling settings on pingenerator.com.

Queue

Omit scheduledTime to add the pin to your scheduling queue. Pins in the queue are automatically assigned time slots based on the scheduling settings you’ve configured for that Pinterest profile on pingenerator.com.

AI Board Selection

Set "useAIBoardSelection": true to let Pin Generator’s AI automatically choose the best board for your pin based on its title and description. The AI will:

Analyze your existing boards and pick the one that best matches the pin’s content.
If no existing board is a good fit, create a new board with an SEO-friendly name.

The response always includes the board object so you can see which board was selected or created.

Rate Limits & Credits

All endpoints consume credits from your Pin Generator account. Image generation and scheduling each cost 1 credit.
When your credits are depleted, all endpoints return a 402 status with an error message.
You can check your remaining credits on your profile page.

Support

For any issues or further assistance, please contact our support team at [email protected].