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

Authentication

All requests require an API key passed as a Bearer token:

Header
Authorization: Bearer sc_your_api_key_here

You can generate and manage your API keys on the API Keys page.

Endpoints

1. Submit a Job

POST /api/v1/generate

Submits 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

FieldTypeRequiredDefaultDescription
keywordstringYesPrimary keyword / article topic
secondary_keywordsstring[]No[]Up to 2 secondary SEO keywords
target_wordsintegerNo600Target article length in words
languagestringNo"English"Article language
nichestringNo"General"Content niche (e.g. "Health", "Finance", "Tech")
writing_stylestringNo"Informative"Informative, Persuasive, Conversational, Educational
tonestringNo"Neutral"Neutral, Formal, Casual, Friendly, Professional
target_audiencestringNo"General Public"Intended audience (e.g. "Beginners", "Experts")
website_typestringNo"Blog"Blog, E-commerce, News, Corporate
content_typestringNo"Educational Content"Educational Content, Product Review, How-To Guide, Listicle
article_structurestring[]NoAI decidesList of section headings (e.g. ["## Intro", "## Section 1", "## Conclusion"])
generate_imagebooleanNotrueWhether to generate a featured image
image_variantstringNo"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

FieldTypeDescription
job_idstringJob identifier
statusstringSee status lifecycle below
progressinteger0–100
current_stepstringHuman-readable description of current step
articlestring | nullFull article in Markdown format (only when completed)
ai_scorefloat | nullAI detection score 0–100 (lower = more human-like)
image_urlstring | nullURL of the generated featured image
errorstring | nullError message (only when failed)

Job Status Lifecycle

StatusMeaning
queuedJob accepted, waiting to start
generatingClaude AI is writing the article
humanizingHumanizing content to reduce AI detection
optimizing_seo_lightRunning SEO optimization
finalizingRunning AI detection check
image_and_linksGenerating image and adding authority links
completedArticle ready — article field is populated
failedGeneration 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 CodeMeaning
401Missing or invalid API key
403API key is inactive
404Job not found
422Invalid request body (e.g. missing keyword)
429Too many concurrent jobs
500Internal 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

  1. 1
    Create a new scenario in Make.com and add a Webhook trigger (or any trigger you prefer).
  2. 2
    Add an HTTP → Make a Request module to submit the job:
    text
    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
             }
    This returns a job_id.
  3. 3
    Add a Repeater module — set Repeats to 12, Initial value to 1.
  4. 4
    Inside the Repeater, add a Sleep module — set it to 15 seconds.
  5. 5
    After 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
  6. 6
    Add a Break module — break when status equals completed or failed.
  7. 7
    After the Repeater, use the result — map article, image_url, and ai_score to 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