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
https://europe-west3-pingenerator-43a15.cloudfunctions.net/highMemLimitApi
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.
access_key: your_access_key_here
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.
Request body
| 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. See the template reference below. |
| title | string | Yes | The title text displayed on the pin. |
| imageURL | string | No | URL 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 … image10new | string | No | URLs 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. |
| 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 … custom100 | string | No | Custom text fields that replace {custom1}, {custom2}, 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"
}'Success response (200)
{
"imageURL": "https://firebasestorage.googleapis.com/v0/b/.../image.jpeg?alt=media"
}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.
Request body
Accepts all parameters from /api/generateImage above, plus the following scheduling parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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. See Finding Board & Section IDs below. |
| altTextnew | string | No | Alt 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. |
| boardSectionId | string | No | Board section ID, if you want to pin to a specific section within the board. |
| 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 creates a new one. When enabled, boardId is not required. |
| aiLanguage | string | No | Language for AI-generated board names and descriptions when useAIBoardSelection is true. Defaults to "English". |
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",
"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 -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)
{
"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
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
| 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. |
| 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. |
| pinterestProfile | string | Yes | The username of your connected Pinterest profile (e.g. "giftsforkevin"). |
| altTextnew | string | No | Alt 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. |
| boardSectionId | string | No | Board section ID, if you want to pin to a specific section within the board. |
| 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 creates a new one. When enabled, boardId is not required. |
| aiLanguage | string | No | Language for AI-generated board names and descriptions when useAIBoardSelection is true. Defaults to "English". |
| boardId | string | Conditional | The Pinterest board ID. Required unless useAIBoardSelection is true. |
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",
"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)
{
"message": "Pin scheduled",
"board": {
"id": "992269799088633298",
"name": "Travel Destinations"
}
}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"} |
| 429 | Rate limit exceeded | {"error": "Rate limit exceeded: at most 60 requests per 60 seconds…"} |
| 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 in the template builder.
| 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
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}:
{
"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
{
"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].
Free accounts include pin credits so you can try the full API workflow — image generation, scheduling and all.