Skip to content

API.md

Latest commit

 

History

History
223 lines (175 loc) · 4.06 KB

API.md

File metadata and controls

223 lines (175 loc) · 4.06 KB
Raw

API Documentation

Base URL

http://localhost:8000/api/v1

Authentication

Currently, the API does not require authentication. For production deployments, add authentication middleware as needed.

Endpoints

Health Check

GET /api/v1/health

Response:

{
  "status": "healthy",
  "version": "2.0.0",
  "environment": "development",
  "features": {
    "pipeline": true,
    "multi_language": true,
    "platform_adaptation": true,
    "narrative_transform": true
  }
}

Analyze Content

POST /api/v1/analyze
Content-Type: application/json

{
  "content": "Your raw content here..."
}

Response:

{
  "status": "success",
  "data": {
    "key_points": ["Point 1", "Point 2"],
    "themes": ["technology", "development"],
    "sentiment": "positive",
    "technical_terms": ["Kubernetes", "Docker"],
    "complexity_level": "advanced"
  },
  "timing": {"total_ms": 150}
}

Extract Topics

POST /api/v1/topics
Content-Type: application/json

{
  "content": "Your raw content here..."
}

Write Chinese Blog

POST /api/v1/write/cn
Content-Type: application/json

{
  "content": "Your raw content here..."
}

Response:

{
  "status": "success",
  "data": {
    "title": "Chinese Blog Title",
    "content": "# Title\\n\\nContent...",
    "word_count": 1200,
    "reading_time": 5,
    "seo_title": "SEO Optimized Title",
    "seo_description": "Meta description"
  }
}

Write English Blog

POST /api/v1/write/en
Content-Type: application/json

{
  "content": "Your raw content here..."
}

Narrative Transformation

POST /api/v1/transform
Content-Type: application/json

{
  "content": "Your raw content here..."
}

Platform Adaptation

POST /api/v1/adapt
Content-Type: application/json

{
  "content": "Your raw content here...",
  "platform": "medium"
}

Supported platforms: medium, wechat, x, xiaohongshu, linkedin, devto, jianshu

Full Pipeline

POST /api/v1/full
Content-Type: application/json

{
  "content": "Your raw content here...",
  "language": "auto",
  "platforms": ["medium", "wechat"],
  "enable_narrative": false,
  "include_full_content": false
}

Parameters:

Field Type Required Default Description
content string Yes - Raw input content
language string No auto cn, en, or auto
platforms array No ["medium", "wechat"] Target platforms
enable_narrative boolean No false Enable storytelling
include_full_content boolean No false Include full output

Response:

{
  "status": "success",
  "pipeline_version": "2.0.0",
  "execution_time_ms": 1250,
  "stages": {
    "preprocessed": { "word_count": 500, "language": "en" },
    "analysis": { "key_points_count": 5, "themes": [...], "sentiment": "positive" },
    "topics": { "primary": "microservices", "titles": { "cn": "...", "en": "..." } },
    "blog_cn": { "title": "...", "word_count": 1200, "reading_time": 5 },
    "blog_en": { "title": "...", "word_count": 800, "reading_time": 4 }
  },
  "platforms": {
    "medium": { "title": "...", "hashtags": [...] },
    "wechat": { "title": "...", "hashtags": [...] }
  }
}

API Info

GET /api/v1/docs

Returns API metadata and available endpoints.

Interactive Documentation

When running in development mode, interactive docs are available at:

Rate Limits

Default: 60 requests per minute per IP address.

Headers:

  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Window: Window size in seconds

Error Responses

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  },
  "status": "error"
}

Common status codes:

  • 400 - Bad Request (invalid input)
  • 429 - Rate Limit Exceeded
  • 500 - Internal Server Error
  • 503 - Service Unavailable