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.
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.
POST https://www.semanticpen.com/api/articlesCreates and manages article generation jobs. Supports bulk operations and returns article IDs.
GET https://www.semanticpen.com/api/articles/{articleId}Retrieves a specific article by ID with full content and metadata.
API requests must be authenticated using a Bearer token in the Authorization header.
You can find your API key on your Account page.
You need to have an active paid plan to use the API. If you are not registered yet, you can register here.
Then go to your Account page inside the settings section to generate an API key.
Do note that the API key is only shown once and cannot be retrieved later from the API, so make sure you save it.
API key will look something like this:
b0cf9c2f-60ad-8ujd-87eb-bd8nm042e092To authenticate your request, you need to pass the API key in the Authorization header like this in every request:
Authorization: Bearer YOUR_API_KEYSemantic Pen Article generation API works with a number of articles. We don't charge anything extra for the word count.
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. |
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.
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. |
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
}),
});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.
| 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.
Note: This list represents countries available for SERP data. Use the country code when making API requests.
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.
For any questions or support, please contact contact@semanticpen.com.