SemanticPen API Documentation

Article Generation API

Our API allows you to generate high-quality articles programmatically, perfect for integrating with custom CMS, performing bulk article generation, or creating your own user interface.

All paid plans can use our API without additional costs. The usage will be the same as using the article generation feature from our website.

Key Features:

Asynchronous article generation
Multiple article modes including Pro Mode, Quick Mode, URL to Article, Bulk Writer, Amazon Product Reviews, and YouTube to Article
Customizable parameters for tone, language, SEO optimization, and more
Optional automatic integration to WordPress, Wix, Webflow, Webhook like Pabbly Connect, Zapier, Integromat, Make, Bubble, Landbot, Integromat, Flowmattic etc.

To use the API, you need an active, paid subscription. Visit your Account page to generate an API key once you have an active plan.

Endpoints

API Key Verification

GET https://www.semanticpen.com/api/verify-key

Verifies if your API key is valid and returns associated user and organization information. Useful for testing authentication before making other API calls.

Article Generation

POST https://www.semanticpen.com/api/articles

Creates and manages article generation jobs. Supports bulk operations and returns article IDs.

Article Retrieval

GET https://www.semanticpen.com/api/articles/{articleId}

Retrieves a specific article by ID with full content and metadata.

Authentication

API requests must be authenticated using a Bearer token in the Authorization header.

You need to have an active paid plan to use the API. If you are not registered yet, you can register here.

Getting Your API Key

Log in to your SemanticPen account
Navigate to your Account page in the settings section
Find the API Keys section
Click "Generate API Key"
Copy and securely store your API key immediately

⚠️ Important: The API key is only shown once and cannot be retrieved later. Make sure you save it securely.

API Key Format

Your API key will look something like this:

b0cf9c2f-60ad-8ujd-87eb-bd8nm042e092

Using Your API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Example Request:

curl -X POST https://www.semanticpen.com/api/articles \
  -H "Authorization: Bearer b0cf9c2f-60ad-8ujd-87eb-bd8nm042e092" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How to Use AI for Content Creation",
    "mode": "pro_mode",
    "language": "en"
  }'

Verifying Your API Key

You can verify if your API key is valid using our verification endpoint:

GET https://www.semanticpen.com/api/verify-key

Example Verification Request:

curl -X GET https://www.semanticpen.com/api/verify-key \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

{
  "success": true,
  "userId": "user-uuid-here",
  "organizationId": "org-uuid-here",
  "message": "API key is valid"
}

Error Response:

{
  "success": false,
  "error": "Invalid API key"
}

Security Best Practices

Store securely: Never expose your API key in client-side code, public repositories, or logs
Environment variables: Use environment variables to store your API key
Rotate regularly: Generate new API keys periodically for enhanced security
Monitor usage: Keep track of your API usage in your account dashboard
Revoke if compromised: Immediately delete and regenerate your API key if you suspect it's been compromised

🔒 Security Note: Treat your API key like a password. Never share it publicly or include it in client-side applications.

Semantic Pen Article generation API works with a number of articles. We don't charge anything extra for the word count.

Request Body

The request body should be a JSON object containing the following properties:

Parameter	Type	Required	Description
targetKeyword	array	Yes	Array of keywords or topics for the article. For single keyword, use string format.
projectName	string	No	Human-readable name for the project containing multiple articles.
personalisationName	string	No	Name of the personalization profile to use for internal linking and content customization.
articleType	string	No	Type of article for specialized processing (e.g., "review", "how-to", "listicle").
articleMode	string	No	The mode of article generation (e.g., "Bulk Writer", "Pro Mode", "Quick Mode"). Default is "Bulk Writer".
targetArticleTopic	string	No	Additional context for the article topic.
language	string	No	The language for the article. Default is "english".
country	string	No	The target country for the article.
toneOfVoice	string	No	The desired tone of voice for the article. Default is "professional".
pointOfView	string	No	The point of view to use in the article. Default is "firstPersonSingular".
includeTableOfContent	boolean	No	Whether to include a table of contents.
includeFAQSection	boolean	No	Whether to include an FAQ section.
includeKeyTakeaways	boolean	No	Whether to include key takeaways.
disableConclusion	boolean	No	Whether to disable the conclusion.
disableIntroduction	boolean	No	Whether to disable the introduction.
aiSeoOptimzation	boolean	No	Whether to apply AI-based SEO optimization.
customWritingStyle	string	No	Custom writing style instructions.
extraTitlePrompt	string	No	Additional prompt for title generation.
backgroundContextEntities	string	No	Additional context or entities for the article.
customLinks	array	No	Custom links to include in the article.
customCTAHeading	string	No	Custom call-to-action heading.
customCTALink	string	No	Custom call-to-action link.
customCTAInstruction	string	No	Instructions for the custom call-to-action.
customOutline	array	No	Custom outline for the article structure.
extraSectionPrompt	string	No	Additional prompt for section generation.
amazonProductURL	string	Conditional	Required for "Amazon Product Review Articles" mode. URL of the Amazon product.
amazonAffiliateTag	string	No	Amazon affiliate tag for product review articles.
youtubeVideoURL	string	Conditional	Required for "Youtube to Article" mode. URL of the YouTube video.
gptVersion	string	No	The GPT model version to use.
maximumExternalLinks	number	No	Maximum number of external links to include.
maximumInternalLinks	number	No	Maximum number of internal links to include.
includeInternalLinks	boolean	No	Whether to include internal links.
includeExternalLinks	boolean	No	Whether to include external links.
readabilityController	string	No	Controls the readability level of the generated content.
sectionLength	string	No	Desired length for each section (e.g., "200" or "400" words).
mediaPreference	string	No	Media preference for articles: "None", "Auto", "Images", "Videos". Default is "None".
maxImages	number	No	Maximum number of images to include in the article.
maxVideos	number	No	Maximum number of videos to include in the article.
imageStyle	string	No	Style for generated images: "digital-art", "photographic", "fantasy-art", "isometric", "3d-model", "anime", "neon-punk".
imageSize	string	No	Size for generated images: "1024x1024", "1152x896", "1216x832", "1344x768", "1536x640", etc.
imageProvider	string	No	Image provider service: "stock-pixabay", "stable-diffusion-v3".
integrationData	object	No	Integration settings for publishing to WordPress/Wix. Contains integrationType, websiteID, categoryName, tagNames, authorName, postStatus, publishImmediately, scheduling options.
selectedKnowledgeBase	object	No	Knowledge base selection for enhanced content generation.
brandVoice	string	No	Brand voice guidelines for consistent content tone and style.
targetAudience	string	No	Target audience description for content personalization.
numberofOutline	string	No	Number of main headings (sections) in the article. Accepts string values from "2" to "10" (or up to "15" if supported). Controls article length.

Parameter Values

Here are the possible values for some of the parameters:

Parameter	Possible Values
articleMode	"Quick Mode", "Pro Mode", "URL to Article", "Youtube to Article", "Amazon Product Review Articles", "Bulk Writer"
language	ISO 639-1 language codes (e.g., "en" for English, "es" for Spanish, etc.). Full list available in the LanguageData array.
country	Country names (e.g., "United States", "United Kingdom", etc.). Full list available in the LanguageData array.
toneOfVoice	"Professional", "Casual", "Friendly", "Authoritative", "Humorous", "Formal", "Inspirational", "Empathetic", "Neutral", "Confident", "Conversational", etc. Custom tones can also be specified.
pointOfView	"firstPersonSingular", "firstPersonPlural", "secondPerson", "thirdPerson"
gptVersion	"gpt-4o-mini", "gpt-3.5-turbo-0125", "gpt-4o", "openai/gpt-4o-mini", "openai/gpt-4o", "anthropic/claude-3.5-sonnet", "anthropic/claude-3-sonnet", "google/gemini-flash-1.5", "google/gemini-pro-1.5", "google/gemini-pro"
readabilityController	"very_easy", "easy", "medium", "hard", "expert", "advanced", "professional"
introStyle	"zero_search_result", "engagement_hook"
imageStyle	"digital-art", "photographic", "fantasy-art", "isometric", "3d-model", "anime", "neon-punk"
imageSize	"1024x1024", "1152x896", "1216x832", "1344x768", "1536x640", "640x1536", "768x1344", "832x1216", "896x1152"
mediaPreference	"None", "Auto", "Images", "Videos"
imageProvider	"stock-pixabay", "stable-diffusion-v3"
numberofOutline	String values from "2" to "15", representing the number of main headings. Each section is approximately 200 words, so total article length is estimated as (numberofOutline × 200) words.

Note: For boolean parameters (e.g., includeTableOfContent, includeFAQSection, etc.), use true or false.

For numeric parameters (e.g., maximumExternalLinks, maximumInternalLinks, etc.), use integer values.

Note: The numberofOutline parameter controls the number of main sections/headings in the article, and thus the approximate article length. Each section is roughly 200 words, so the total word count is an estimate.

Response

The API responds with a JSON object containing the following properties:

Property	Type	Description
articleIds	array	Array of generated article IDs (UUIDs) for bulk operations.
projectId	string	Project ID (UUID) grouping multiple articles together.
redisKey	string	Cache key for prefetched data (returned for task="prefetch").
status	string	Article generation status: "queued", "processing", "finished", "failed".
progress	number	Generation progress percentage (0-100).
error	string	Error message if the request fails.
message	string	Human-readable status message.

Example Requests

API Key Verification

// Test your API key before making other requests
fetch("https://www.semanticpen.com/api/verify-key", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log("API key is valid!");
    console.log("User ID:", data.userId);
    console.log("Organization ID:", data.organizationId);
  } else {
    console.error("API key validation failed:", data.error);
  }
})
.catch(error => {
  console.error("Error:", error);
});

Basic Article Generation

fetch("https://www.semanticpen.com/api/articles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: ["sustainable living tips", "eco-friendly lifestyle"],
    articleMode: "Bulk Writer",
    language: "english",
    country: "United States",
    toneOfVoice: "informative",
    pointOfView: "secondPerson",
    includeTableOfContent: true,
    includeFAQSection: true,
    aiSeoOptimzation: true,
    projectName: "Sustainability Blog Series",
    personalisationName: "eco-brand-voice"
  }),
});

Bulk Article Generation with Media

fetch("https://www.semanticpen.com/api/articles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: ["digital marketing trends", "SEO best practices", "content marketing"],
    articleMode: "Bulk Writer",
    projectName: "Marketing Blog Q1 2024",
    mediaPreference: "Images",
    maxImages: 3,
    imageStyle: "photographic",
    imageSize: "1024x1024",
    imageProvider: "stock-pixabay",
    brandVoice: "Professional and authoritative tone with actionable insights",
    targetAudience: "Marketing professionals and business owners",
    language: "english",
    country: "United States",
    toneOfVoice: "professional",
    includeTableOfContent: true,
    includeFAQSection: true,
    aiSeoOptimzation: true
  }),
});

Article Generation with WordPress Integration

fetch("https://www.semanticpen.com/api/articles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: "productivity tips for remote workers",
    articleMode: "Bulk Writer",
    projectName: "Remote Work Blog",
    integrationData: {
      integrationType: "WordPress",
      websiteID: "your-website-id",
      categoryName: ["Productivity", "Remote Work"],
      tagNames: ["productivity", "remote", "work-from-home"],
      authorName: "John Doe",
      postStatus: "draft",
      publishImmediately: false,
      scheduleStartDate: "2024-01-15",
      scheduleEndDate: "2024-01-30",
      postFrequency: "daily"
    },
    language: "english",
    country: "United States",
    toneOfVoice: "friendly",
    pointOfView: "secondPerson",
    includeTableOfContent: true,
    includeFAQSection: true,
    aiSeoOptimzation: true
  }),
});

Amazon Product Review Article

fetch("https://www.semanticpen.com/api/articles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: "best eco-friendly water bottle",
    articleMode: "Amazon Product Review Articles",
    amazonProductURL: "https://www.amazon.com/Redragon-S101-Keyboard-Ergonomic-Programmable/dp/B00NLZUM36/",
    amazonAffiliateTag: "your-affiliate-tag-20",
    language: "english",
    country: "United States",
    toneOfVoice: "persuasive",
    pointOfView: "firstPersonSingular",
    includeTableOfContent: true,
    includeFAQSection: true,
    aiSeoOptimzation: true
  }),
});

YouTube to Article

fetch("https://www.semanticpen.com/api/articles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: "machine learning basics",
    articleMode: "Youtube to Article",
    youtubeVideoURL: "https://www.youtube.com/watch?v=creuUvqslYg",
    language: "english",
    country: "United States",
    toneOfVoice: "educational",
    pointOfView: "thirdPerson",
    includeTableOfContent: true,
    includeFAQSection: true,
    aiSeoOptimzation: true
  }),
});

Error Handling

The API uses standard HTTP response codes to indicate the success or failure of requests. In case of an error, the response will include an `error` field with a description of the issue.

Common error codes:

400: Bad Request - The request was invalid or cannot be served.
401: Unauthorized - The request requires authentication or the provided API key is invalid.
403: Forbidden - The server understood the request but refuses to authorize it.
500: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.

Available Languages

Language Code	Language Name	Country
ar	Arabic	Saudi Arabia
bg	Bulgarian	Bulgaria
zh	Chinese (Simplified)	China
zh-tw	Chinese (Traditional)	Taiwan
hr	Croatian	Croatia
cs	Czech	Czech Republic
da	Danish	Denmark
nl	Dutch	Netherlands
en	English	United States
et	Estonian	Estonia
fi	Finnish	Finland
fr	French	France
de-formal-sie	German Formal (Sie)	Germany
de-informal-du	German Informal (du)	Germany
el	Greek	Greece
iw	Hebrew	N/A
hi	Hindi	India
hu	Hungarian	Hungary
id	Indonesian	Indonesia
ga	Irish	Ireland
it	Italian	Italy
ja	Japanese	Japan
ko	Korean	South Korea
la	Latin	Vatican City
lv	Latvian	Latvia
lt	Lithuanian	Lithuania
no	Norwegian	Norway
pl	Polish	Poland
pt	Portuguese	Portugal
ro	Romanian	Romania
ru	Russian	Russia
gd	Scottish Gaelic	Scotland
sr	Serbian	Serbia
sk	Slovak	Slovakia
sl	Slovenian	Slovenia
es	Spanish (idioma español)	Spain
sv	Swedish (svenska språket)	Sweden
th	Thai (ภาษาไทย)	Thailand
tr	Turkish	Turkey
uk	Ukrainian	Ukraine
vi	Vietnamese	Vietnam

Note: This list includes the main supported languages. Some languages may have additional variants or dialects.

SERP Countries and Codes

AngolaAO

ArgentinaAR

ArmeniaAM

AustraliaAU

AustriaAT

BahrainBH

BangladeshBD

BelgiumBE

BoliviaBO

BrazilBR

BulgariaBG

CanadaCA

ChileCL

ColombiaCO

Costa RicaCR

CroatiaHR

CyprusCY

Czech RepublicCZ

DenmarkDK

EcuadorEC

EgyptEG

El SalvadorSV

EstoniaEE

FinlandFI

FranceFR

GermanyDE

GreeceGR

GuatemalaGT

Hong KongHK

HungaryHU

IndiaIN

IndonesiaID

IrelandIE

IsraelIL

ItalyIT

JapanJP

JordanJO

KenyaKE

LatviaLV

LithuaniaLT

MalaysiaMY

MaltaMT

MexicoMX

MoroccoMA

NetherlandsNL

New ZealandNZ

NicaraguaNI

NigeriaNG

NorwayNO

PakistanPK

ParaguayPY

PeruPE

PolandPL

PortugalPT

RomaniaRO

Russian FederationRU

Saudi ArabiaSA

SerbiaRS

SingaporeSG

SlovakiaSK

SloveniaSI

South AfricaZA

South KoreaKR

SpainES

Sri LankaLK

SwedenSE

SwitzerlandCH

TaiwanTW

ThailandTH

TunisiaTN

TurkeyTR

UkraineUA

United Arab EmiratesAE

United KingdomGB

United StatesUS

UruguayUY

VenezuelaVE

Viet NamVN

Note: This list represents countries available for SERP data. Use the country code when making API requests.

Rate Limiting

API requests are subject to rate limiting to ensure fair usage. If you exceed the rate limit, you'll receive a 429 (Too Many Requests) response. Please contact support for information about your specific rate limits.

Additional Notes

The API now supports both string and array formats for `targetKeyword`. Use arrays for bulk operations with multiple keywords.
API key authentication is required. The system automatically retrieves your organization context and user details from the provided API key.
The `articleMode` parameter determines the type of article generation. Available modes include "Bulk Writer", "Pro Mode", "Quick Mode", "Amazon Product Review Articles", and "Youtube to Article".
When using the "Amazon Product Review Articles" mode, the `amazonProductURL` is required.
For the "Youtube to Article" mode, the `youtubeVideoURL` is required.
**Bulk Operations**: Use `projectName` to group multiple articles together. The API returns a `projectId` and array of `articleIds`.
**Media Support**: Set `mediaPreference` to "Images" or "Videos" to include media in articles. Configure `imageStyle`, `imageSize`, and `imageProvider` for customization.
**Personalization**: Use `personalisationName` to apply saved personalization profiles for consistent brand voice and internal linking.
**Publishing Integration**: Use `integrationData` to automatically publish articles to WordPress or Wix with scheduling and categorization.
**Knowledge Base**: Use `selectedKnowledgeBase` to enhance articles with organization-specific content and context.
The generated articles are queued for processing. The response includes article IDs that can be used to check the status or retrieve the completed articles later.
**Rate Limiting**: The API implements credit-based usage tracking. Each request consumes credits based on article length and complexity.

For any questions or support, please contact contact@semanticpen.com.

Article Generation API

Our API allows you to generate high-quality articles programmatically, perfect for integrating with custom CMS, performing bulk article generation, or creating your own user interface.

All paid plans can use our API without additional costs. The usage will be the same as using the article generation feature from our website.

Key Features:

Asynchronous article generation

Multiple article modes including Pro Mode, Quick Mode, URL to Article, Bulk Writer, Amazon Product Reviews, and YouTube to Article

Customizable parameters for tone, language, SEO optimization, and more

Optional automatic integration to WordPress, Wix, Webflow, Webhook like Pabbly Connect, Zapier, Integromat, Make, Bubble, Landbot, Integromat, Flowmattic etc.

To use the API, you need an active, paid subscription. Visit your Account page to generate an API key once you have an active plan.

curl -X POST https://www.semanticpen.com/api/articles \ -H "Authorization: Bearer b0cf9c2f-60ad-8ujd-87eb-bd8nm042e092" \ -H "Content-Type: application/json" \ -d '{ "title": "How to Use AI for Content Creation", "mode": "pro_mode", "language": "en" }'

Parameter

Type

Required

Description

targetKeyword

array

Yes

Array of keywords or topics for the article. For single keyword, use string format.

projectName

string

Human-readable name for the project containing multiple articles.

personalisationName

string

Name of the personalization profile to use for internal linking and content customization.

articleType

string

Type of article for specialized processing (e.g., "review", "how-to", "listicle").

articleMode

string

The mode of article generation (e.g., "Bulk Writer", "Pro Mode", "Quick Mode"). Default is "Bulk Writer".

targetArticleTopic

string

Additional context for the article topic.

language

string

The language for the article. Default is "english".

country

string

The target country for the article.

toneOfVoice

string

The desired tone of voice for the article. Default is "professional".

pointOfView

string

The point of view to use in the article. Default is "firstPersonSingular".

includeTableOfContent

boolean

Whether to include a table of contents.

includeFAQSection

boolean

Whether to include an FAQ section.

includeKeyTakeaways

boolean

Whether to include key takeaways.

disableConclusion

boolean

Whether to disable the conclusion.

disableIntroduction

boolean

Whether to disable the introduction.

aiSeoOptimzation

boolean

Whether to apply AI-based SEO optimization.

customWritingStyle

string

Custom writing style instructions.

extraTitlePrompt

string

Additional prompt for title generation.

backgroundContextEntities

string

Additional context or entities for the article.

customLinks

array

Custom links to include in the article.

customCTAHeading

string

Custom call-to-action heading.

customCTALink

string

Custom call-to-action link.

customCTAInstruction

string

Instructions for the custom call-to-action.

customOutline

array

Custom outline for the article structure.

extraSectionPrompt

string

Additional prompt for section generation.

amazonProductURL

string

Conditional

Required for "Amazon Product Review Articles" mode. URL of the Amazon product.

amazonAffiliateTag

string

Amazon affiliate tag for product review articles.

youtubeVideoURL

string

Conditional

Required for "Youtube to Article" mode. URL of the YouTube video.

gptVersion

string

The GPT model version to use.

maximumExternalLinks

number

Maximum number of external links to include.

maximumInternalLinks

number

Maximum number of internal links to include.

includeInternalLinks

boolean

Whether to include internal links.

includeExternalLinks

boolean

Whether to include external links.

readabilityController

string

Controls the readability level of the generated content.

sectionLength

string

Desired length for each section (e.g., "200" or "400" words).

mediaPreference

string

Media preference for articles: "None", "Auto", "Images", "Videos". Default is "None".

maxImages

number

Maximum number of images to include in the article.

maxVideos

number

Maximum number of videos to include in the article.

imageStyle

string

Style for generated images: "digital-art", "photographic", "fantasy-art", "isometric", "3d-model", "anime", "neon-punk".

imageSize

string

Size for generated images: "1024x1024", "1152x896", "1216x832", "1344x768", "1536x640", etc.

imageProvider

string

Image provider service: "stock-pixabay", "stable-diffusion-v3".

integrationData

object

Integration settings for publishing to WordPress/Wix. Contains integrationType, websiteID, categoryName, tagNames, authorName, postStatus, publishImmediately, scheduling options.

selectedKnowledgeBase

object

Knowledge base selection for enhanced content generation.

brandVoice

string

Brand voice guidelines for consistent content tone and style.

targetAudience

string

Target audience description for content personalization.

numberofOutline

string

Number of main headings (sections) in the article. Accepts string values from "2" to "10" (or up to "15" if supported). Controls article length.

Parameter

Possible Values

articleMode

"Quick Mode", "Pro Mode", "URL to Article", "Youtube to Article", "Amazon Product Review Articles", "Bulk Writer"

language

ISO 639-1 language codes (e.g., "en" for English, "es" for Spanish, etc.). Full list available in the LanguageData array.

country

Country names (e.g., "United States", "United Kingdom", etc.). Full list available in the LanguageData array.

toneOfVoice

"Professional", "Casual", "Friendly", "Authoritative", "Humorous", "Formal", "Inspirational", "Empathetic", "Neutral", "Confident", "Conversational", etc. Custom tones can also be specified.

pointOfView

"firstPersonSingular", "firstPersonPlural", "secondPerson", "thirdPerson"

gptVersion

"gpt-4o-mini", "gpt-3.5-turbo-0125", "gpt-4o", "openai/gpt-4o-mini", "openai/gpt-4o", "anthropic/claude-3.5-sonnet", "anthropic/claude-3-sonnet", "google/gemini-flash-1.5", "google/gemini-pro-1.5", "google/gemini-pro"

readabilityController

"very_easy", "easy", "medium", "hard", "expert", "advanced", "professional"

introStyle

"zero_search_result", "engagement_hook"

imageStyle

"digital-art", "photographic", "fantasy-art", "isometric", "3d-model", "anime", "neon-punk"

imageSize

"1024x1024", "1152x896", "1216x832", "1344x768", "1536x640", "640x1536", "768x1344", "832x1216", "896x1152"

mediaPreference

"None", "Auto", "Images", "Videos"

imageProvider

"stock-pixabay", "stable-diffusion-v3"

numberofOutline

String values from "2" to "15", representing the number of main headings. Each section is approximately 200 words, so total article length is estimated as (numberofOutline × 200) words.

Property

Type

Description

articleIds

array

Array of generated article IDs (UUIDs) for bulk operations.

projectId

string

Project ID (UUID) grouping multiple articles together.

redisKey

string

Cache key for prefetched data (returned for task="prefetch").

status

string

Article generation status: "queued", "processing", "finished", "failed".

progress

number

Generation progress percentage (0-100).

error

string

Error message if the request fails.

message

string

Human-readable status message.

// Test your API key before making other requests fetch("https://www.semanticpen.com/api/verify-key", { method: "GET", headers: { "Authorization": "Bearer YOUR_API_KEY" } }) .then(response => response.json()) .then(data => { if (data.success) { console.log("API key is valid!"); console.log("User ID:", data.userId); console.log("Organization ID:", data.organizationId); } else { console.error("API key validation failed:", data.error); } }) .catch(error => { console.error("Error:", error); });

fetch("https://www.semanticpen.com/api/articles", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ targetKeyword: ["sustainable living tips", "eco-friendly lifestyle"], articleMode: "Bulk Writer", language: "english", country: "United States", toneOfVoice: "informative", pointOfView: "secondPerson", includeTableOfContent: true, includeFAQSection: true, aiSeoOptimzation: true, projectName: "Sustainability Blog Series", personalisationName: "eco-brand-voice" }), });

fetch("https://www.semanticpen.com/api/articles", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ targetKeyword: ["digital marketing trends", "SEO best practices", "content marketing"], articleMode: "Bulk Writer", projectName: "Marketing Blog Q1 2024", mediaPreference: "Images", maxImages: 3, imageStyle: "photographic", imageSize: "1024x1024", imageProvider: "stock-pixabay", brandVoice: "Professional and authoritative tone with actionable insights", targetAudience: "Marketing professionals and business owners", language: "english", country: "United States", toneOfVoice: "professional", includeTableOfContent: true, includeFAQSection: true, aiSeoOptimzation: true }), });

fetch("https://www.semanticpen.com/api/articles", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ targetKeyword: "productivity tips for remote workers", articleMode: "Bulk Writer", projectName: "Remote Work Blog", integrationData: { integrationType: "WordPress", websiteID: "your-website-id", categoryName: ["Productivity", "Remote Work"], tagNames: ["productivity", "remote", "work-from-home"], authorName: "John Doe", postStatus: "draft", publishImmediately: false, scheduleStartDate: "2024-01-15", scheduleEndDate: "2024-01-30", postFrequency: "daily" }, language: "english", country: "United States", toneOfVoice: "friendly", pointOfView: "secondPerson", includeTableOfContent: true, includeFAQSection: true, aiSeoOptimzation: true }), });

fetch("https://www.semanticpen.com/api/articles", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ targetKeyword: "best eco-friendly water bottle", articleMode: "Amazon Product Review Articles", amazonProductURL: "https://www.amazon.com/Redragon-S101-Keyboard-Ergonomic-Programmable/dp/B00NLZUM36/", amazonAffiliateTag: "your-affiliate-tag-20", language: "english", country: "United States", toneOfVoice: "persuasive", pointOfView: "firstPersonSingular", includeTableOfContent: true, includeFAQSection: true, aiSeoOptimzation: true }), });

fetch("https://www.semanticpen.com/api/articles", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ targetKeyword: "machine learning basics", articleMode: "Youtube to Article", youtubeVideoURL: "https://www.youtube.com/watch?v=creuUvqslYg", language: "english", country: "United States", toneOfVoice: "educational", pointOfView: "thirdPerson", includeTableOfContent: true, includeFAQSection: true, aiSeoOptimzation: true }), });

Language Code

Language Name

Country

Arabic

Saudi Arabia

Bulgarian

Bulgaria

Chinese (Simplified)

China

zh-tw

Chinese (Traditional)

Taiwan

Croatian

Croatia

Czech

Czech Republic

Danish

Denmark

Dutch

Netherlands

English

United States

Estonian

Estonia

Finnish

Finland

French

France

de-formal-sie

German Formal (Sie)

Germany

de-informal-du

German Informal (du)

Germany

Greek

Greece

Hebrew

N/A

Hindi

India

Hungarian

Hungary

Indonesian

Indonesia

Irish

Ireland

Italian

Italy

Japanese

Japan

Korean

South Korea

Latin

Vatican City

Latvian

Latvia

Lithuanian

Lithuania

Norwegian

Norway

Polish

Poland

Portuguese

Portugal

Romanian

Romania

Russian

Russia

Scottish Gaelic

Scotland

Serbian

Serbia

Slovak

Slovakia

Slovenian

Slovenia

Spanish (idioma español)

Spain

Swedish (svenska språket)

Sweden

Thai (ภาษาไทย)

Thailand

Turkish

Turkey

Ukrainian

Ukraine

Vietnamese

Vietnam