Article Generation API
Developer Guide
Generate SEO articles programmatically. Because article generation takes 60–120 seconds, the API uses a fire-and-poll pattern: you submit a job and get a job_id immediately, then poll until the article is ready.
Base URL
Base URL
https://generatecontentwithaiservice-g5zrtckfda-ue.a.run.appAuthentication
All requests require an API key passed as a Bearer token:
Header
Authorization: Bearer sc_your_api_key_hereYou can generate and manage your API keys on the API Keys page.
Endpoints
1. Submit a Job
POST /api/v1/generateSubmits an article generation job. Returns immediately with a job_id.
Request
bash
curl -X POST https://generatecontentwithaiservice-g5zrtckfda-ue.a.run.app/api/v1/generate \
-H "Authorization: Bearer sc_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"keyword": "best running shoes 2025",
"target_words": 800
}'Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
keyword | string | Yes | — | Primary keyword / article topic |
secondary_keywords | string[] | No | [] | Up to 2 secondary SEO keywords |
target_words | integer | No | 600 | Target article length in words |
language | string | No | "English" | Article language |
niche | string | No | "General" | Content niche (e.g. "Health", "Finance", "Tech") |
writing_style | string | No | "Informative" | Informative, Persuasive, Conversational, Educational |
tone | string | No | "Neutral" | Neutral, Formal, Casual, Friendly, Professional |
target_audience | string | No | "General Public" | Intended audience (e.g. "Beginners", "Experts") |
website_type | string | No | "Blog" | Blog, E-commerce, News, Corporate |
content_type | string | No | "Educational Content" | Educational Content, Product Review, How-To Guide, Listicle |
article_structure | string[] | No | AI decides | List of section headings (e.g. ["## Intro", "## Section 1", "## Conclusion"]) |
generate_image | boolean | No | true | Whether to generate a featured image |
image_variant | string | No | "standard" | Image quality: fast, standard, ultra |
Response
json
{
"job_id": "6a3593e6696e2a17267f241b",
"status": "queued",
"poll_url": "/api/v1/jobs/6a3593e6696e2a17267f241b",
"estimated_seconds": 90
}2. Poll Job Status
GET /api/v1/jobs/{job_id}Returns the current status and result of a job.
Request
bash
curl https://generatecontentwithaiservice-g5zrtckfda-ue.a.run.app/api/v1/jobs/6a3593e6696e2a17267f241b \
-H "Authorization: Bearer sc_your_api_key_here"Response — In Progress
json
{
"job_id": "6a3593e6696e2a17267f241b",
"status": "humanizing",
"progress": 50,
"current_step": "Humanizing content...",
"article": null,
"ai_score": null,
"image_url": null,
"error": null
}Response — Completed
json
{
"job_id": "6a3593e6696e2a17267f241b",
"status": "completed",
"progress": 100,
"current_step": "Article generation completed successfully",
"article": "# Best Running Shoes 2025\n\n...",
"ai_score": 8.0,
"image_url": "https://v3b.fal.media/files/b/example.jpg",
"error": null
}Response — Failed
json
{
"job_id": "6a3593e6696e2a17267f241b",
"status": "failed",
"progress": 0,
"current_step": "Generation failed",
"article": null,
"ai_score": null,
"image_url": null,
"error": "Humanization failed: resource exhausted"
}Response Fields
| Field | Type | Description |
|---|---|---|
job_id | string | Job identifier |
status | string | See status lifecycle below |
progress | integer | 0–100 |
current_step | string | Human-readable description of current step |
article | string | null | Full article in Markdown format (only when completed) |
ai_score | float | null | AI detection score 0–100 (lower = more human-like) |
image_url | string | null | URL of the generated featured image |
error | string | null | Error message (only when failed) |
Job Status Lifecycle
| Status | Meaning |
|---|---|
queued | Job accepted, waiting to start |
generating | Claude AI is writing the article |
humanizing | Humanizing content to reduce AI detection |
optimizing_seo_light | Running SEO optimization |
finalizing | Running AI detection check |
image_and_links | Generating image and adding authority links |
completed | Article ready — article field is populated |
failed | Generation failed — check error field |
Rate Limits
5 concurrent jobs per API key at a time. Exceeding this returns
429 Too Many Requests.Error Codes
| HTTP Code | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | API key is inactive |
404 | Job not found |
422 | Invalid request body (e.g. missing keyword) |
429 | Too many concurrent jobs |
500 | Internal server error |
Code Examples
Python
python
import requests
import time
API_KEY = "sc_your_api_key_here"
BASE_URL = "https://generatecontentwithaiservice-g5zrtckfda-ue.a.run.app"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
# Submit job
response = requests.post(f"{BASE_URL}/api/v1/generate", headers=HEADERS, json={
"keyword": "best running shoes 2025",
"target_words": 800,
"writing_style": "Informative",
"tone": "Friendly",
"generate_image": True,
})
job = response.json()
job_id = job["job_id"]
print(f"Job submitted: {job_id}")
# Poll until done
while True:
result = requests.get(f"{BASE_URL}/api/v1/jobs/{job_id}", headers=HEADERS).json()
status = result["status"]
print(f"Status: {status} — {result['current_step']}")
if status == "completed":
print("\nArticle:\n", result["article"][:500])
print("\nImage URL:", result["image_url"])
print("AI Score:", result["ai_score"])
break
elif status == "failed":
print("Failed:", result["error"])
break
time.sleep(10)Node.js
javascript
const API_KEY = "sc_your_api_key_here";
const BASE_URL = "https://generatecontentwithaiservice-g5zrtckfda-ue.a.run.app";
const headers = { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" };
async function generateArticle(keyword, options = {}) {
const res = await fetch(`${BASE_URL}/api/v1/generate`, {
method: "POST",
headers,
body: JSON.stringify({ keyword, target_words: 800, generate_image: true, ...options }),
});
const { job_id } = await res.json();
console.log("Job submitted:", job_id);
while (true) {
await new Promise(r => setTimeout(r, 10000));
const poll = await fetch(`${BASE_URL}/api/v1/jobs/${job_id}`, { headers });
const result = await poll.json();
console.log(`Status: ${result.status} — ${result.current_step}`);
if (result.status === "completed") {
console.log("Article:", result.article.slice(0, 500));
console.log("Image URL:", result.image_url);
return result;
}
if (result.status === "failed") throw new Error(result.error);
}
}
generateArticle("best running shoes 2025", { tone: "Friendly" });PHP
php
<?php
$API_KEY = "sc_your_api_key_here";
$BASE_URL = "https://generatecontentwithaiservice-g5zrtckfda-ue.a.run.app";
function apiRequest($method, $path, $data = null) {
global $API_KEY, $BASE_URL;
$ch = curl_init("$BASE_URL$path");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
]);
if ($method === "POST") {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
}
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
$job = apiRequest("POST", "/api/v1/generate", [
"keyword" => "best running shoes 2025",
"target_words" => 800,
"generate_image" => true,
]);
$job_id = $job["job_id"];
echo "Job submitted: $job_id\n";
while (true) {
sleep(10);
$result = apiRequest("GET", "/api/v1/jobs/$job_id");
echo "Status: {$result['status']} — {$result['current_step']}\n";
if ($result["status"] === "completed") {
echo "Article: " . substr($result["article"], 0, 500) . "\n";
break;
}
if ($result["status"] === "failed") {
echo "Failed: {$result['error']}\n";
break;
}
}Using with Make.com (No Code)
Make.com lets you connect the SpeedContent API to anything — Google Sheets, Notion, WordPress, email, Slack — with zero coding.
Step-by-step setup
- 1Create a new scenario in Make.com and add a Webhook trigger (or any trigger you prefer).
- 2Add an HTTP → Make a Request module to submit the job:This returns atext
URL: https://generatecontentwithaiservice-g5zrtckfda-ue.a.run.app/api/v1/generate Method: POST Headers: Authorization: Bearer YOUR_API_KEY_HERE Content-Type: application/json Body: { "keyword": "{{your keyword variable}}", "target_words": 800, "generate_image": true }job_id. - 3Add a Repeater module — set Repeats to 12, Initial value to 1.
- 4Inside the Repeater, add a Sleep module — set it to 15 seconds.
- 5After Sleep, add another HTTP module to poll:text
URL: https://generatecontentwithaiservice-g5zrtckfda-ue.a.run.app/api/v1/jobs/{{job_id}} Method: GET Headers: Authorization: Bearer YOUR_API_KEY_HERE - 6Add a Break module — break when
statusequalscompletedorfailed. - 7After the Repeater, use the result — map
article,image_url, andai_scoreto your destination.
Your API key is available on the API Keys page.
Tips
- →Poll every 10–15 seconds — generation typically takes 60–120 seconds
- →Minimum 600 words recommended — very short articles (< 400 words) may fail humanization
- →article is Markdown — render it with any Markdown parser for display
- →ai_score is 0–100; scores below 20 are considered human-like
- →image_url is a CDN-hosted image ready to embed directly