// developer reference

Pin Generator API

Programmatically create Pinterest pin images, schedule them to your connected Pinterest profiles, or do both in a single request. Every API call consumes credits from your account, just like using the Pin Generator UI.

Overview

The API exposes three endpoints: generate a pin image, generate and schedule in one step, and schedule an already-hosted image. All endpoints accept JSON request bodies and return JSON responses.

Base URL

base url
https://europe-west3-pingenerator-43a15.cloudfunctions.net/highMemLimitApi
✦Prefer talking to an AI instead of writing code? Pin Generator also ships an MCP server that lets Claude, ChatGPT, Cursor and other AI assistants generate and schedule pins for you.

Authentication

All requests must include your access key as a header. 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.

request header
access_key: your_access_key_here

1. Generate Image

POST/api/generateImage1 credit

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.

Request body

ParameterTypeRequiredDescription
templatestringYesTemplate ID, template name, or "RandomTemplate" to pick a random basic template. Template IDs can be found in the URL when editing a template. See the template reference below.
titlestringYesThe title text displayed on the pin.
imageURLstringNoURL of the image for the first image layer. Must be a publicly accessible image URL. Ignored if image1 is also provided. See Multiple Images below.
image1 … image10newstringNoURLs for separate image layers in a multi-image template, assigned in order (image1 → first layer, image2 → second, and so on). Same field names as CSV uploads. See Multiple Images below.
urlstringNoThe destination URL the pin links to.
urlTextstringNoDisplay text for the URL shown on the pin (e.g. yoursite.com).
colorstringNoHex color code for the pin (with or without #). Example: "ae3ac4" or "#ae3ac4".
descriptionstringNoDescription text for the pin.
custom1 … custom100stringNoCustom text fields that replace {custom1}, {custom2}, etc. placeholders in your template's text layers. See Custom Fields below.

Example request

curl
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"
  }'

Success response (200)

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

2. Generate Image & Schedule

POST/api/generateAndSchedule1 credit

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.

Request body

Accepts all parameters from /api/generateImage above, plus the following scheduling parameters:

ParameterTypeRequiredDescription
pinterestProfilestringYesThe username of your connected Pinterest profile (e.g. "giftsforkevin").
boardIdstringConditionalThe Pinterest board ID to pin to. Required unless useAIBoardSelection is true. See Finding Board & Section IDs below.
altTextnewstringNoAlt text for the pin image, used by screen readers and by Pinterest to understand the image. Up to 500 characters — longer values are truncated when the pin is posted.
boardSectionIdstringNoBoard section ID, if you want to pin to a specific section within the board.
scheduledTimestringNoISO 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.
useAIBoardSelectionbooleanNoSet to true to let AI automatically select the best board based on the pin's title and description. If no suitable board exists, AI creates a new one. When enabled, boardId is not required.
aiLanguagestringNoLanguage for AI-generated board names and descriptions when useAIBoardSelection is true. Defaults to "English".

Example request — manual board

curl
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",
    "altText": "Turquoise water and white sand at a beach in Brazil",
    "pinterestProfile": "your_pinterest_username",
    "boardId": "your_board_id",
    "scheduledTime": "2026-03-15T14:00:00.000Z"
  }'

Example request — AI board selection

curl
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",
    "description": "Discover the most beautiful beaches in Brazil",
    "pinterestProfile": "your_pinterest_username",
    "useAIBoardSelection": true
  }'

Success response (200)

response
{
  "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 (i.e. scheduledTime was omitted), the message reads "Pin generated and added to scheduling queue".

3. Schedule Existing Image

POST/api/schedulePin1 credit

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.

Request body

ParameterTypeRequiredDescription
mediaURLstringYesThe URL of the image to schedule. This can be an image URL returned from /api/generateImage or any publicly accessible image URL.
titlestringNoTitle for the pin on Pinterest.
descriptionstringNoDescription for the pin on Pinterest.
urlstringNoThe destination URL the pin links to.
pinterestProfilestringYesThe username of your connected Pinterest profile (e.g. "giftsforkevin").
altTextnewstringNoAlt text for the pin image, used by screen readers and by Pinterest to understand the image. Up to 500 characters — longer values are truncated when the pin is posted.
boardSectionIdstringNoBoard section ID, if you want to pin to a specific section within the board.
scheduledTimestringNoISO 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.
useAIBoardSelectionbooleanNoSet to true to let AI automatically select the best board based on the pin's title and description. If no suitable board exists, AI creates a new one. When enabled, boardId is not required.
aiLanguagestringNoLanguage for AI-generated board names and descriptions when useAIBoardSelection is true. Defaults to "English".
boardIdstringConditionalThe Pinterest board ID. Required unless useAIBoardSelection is true.

Example request

curl
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",
    "altText": "Turquoise water and white sand at a beach 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)

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

Error Responses

StatusMeaningExample
400Missing required parameter{"error": "template is required"}
401Invalid access key{"error": "User not found"}
402No credits remaining{"error": "Pin generation credits depleted"}
403Missing access key{"error": "Unauthorized"}
404Resource not found{"error": "Template not found"}
429Rate limit exceeded{"error": "Rate limit exceeded: at most 60 requests per 60 seconds…"}
500Server 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 in the template builder.

Template NameFriendly NameStyle
CenterWaveCenter waveWavey
TextBlobText blobWavey
WaveySplitWavey splitWavey
ColorBlobsColor blobsWavey
SquareTextWithLandscapeImageBig text with landscape imageSquare
TextOverlayText overlaySquare
TextSideRightText side rightSquare
BigTopTextBig top textSquare
StandardTemplateStandardStandard
LandscapeFriendlyLandscape friendlyStandard
FullImageWithBannerFull image with bannerStandard
PortraitFriendlyPortrait friendlyStandard
ImageOnlyImage onlyStandard
BlankWithFrameImage only with frameStandard
CircleImageWithBannerCircle image with bannerStandard

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

1. 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).
2. When calling the API, pass the corresponding field (e.g. "custom1": "Your text here") in the request body.
3. 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}:

request body
{
  "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 Schedule Existing Image since no image rendering occurs.

Multiple Images

Templates with more than one image layer can be populated in a single request using the same field names as CSV uploads: image1 through image10.

How it works

Images are assigned in order to each template layer that uses detected images. image1 goes to the first such layer, image2 to the second, and so on. Logo layers are left unchanged. If the template has more image layers than you provide, the list wraps around.

imageURL is still supported and fills the first image layer when image1 is omitted. If both are sent, image1 is used.

Example

request body
{
  "template": "your_template_id",
  "title": "Summer Recipes",
  "image1": "https://example.com/hero.jpg",
  "image2": "https://example.com/detail.jpg",
  "image3": "https://example.com/lifestyle.jpg"
}

Multiple images are available on the Generate Image and Generate Image & Schedule endpoints. A request still costs 1 credit regardless of how many image layers you populate.

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:

1. Hover over the copy icon next to any board name to see its ID in the tooltip.
2. Click the icon to copy the ID to your clipboard.
3. 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.

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.

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 analyzes your existing boards and picks the one that best matches the pin's content — and if no existing board is a good fit, it creates a new board with an SEO-friendly name.

Rate Limits & Credits

Each access key is limited to 60 requests per minute across all API endpoints. When the limit is exceeded, requests return a 429 status with a Retry-After header — wait and slow down before retrying.

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].

Ready to automate your pins?

Free accounts include pin credits so you can try the full API workflow — image generation, scheduling and all.