Documentation

AI Services API

SmartCV AI services API documentation, including ATS analysis, intelligent optimization, theme recommendations and other AI features

Updated: 12/30/2024

SmartCV AI services provide powerful artificial intelligence features, including ATS compatibility analysis, intelligent resume optimization, theme recommendations, and more.

📋 API Endpoint Overview

EndpointMethodDescription
/api/ai/analyzePOSTATS compatibility analysis
/api/ai/generatePOSTAI content generation
/api/ai/theme-recommendationPOSTTheme recommendation

🔍 ATS Compatibility Analysis

Endpoint: POST /api/ai/analyze

Description: Analyze the match between resume and job description, providing ATS compatibility scores and optimization suggestions

Authentication: Required login

Request Body:

{
  "resumeData": {
    "personalInfo": {
      "name": "Zhang San",
      "email": "zhangsan@example.com",
      "phone": "13800138000",
      "summary": "5 years of frontend development experience, proficient in React, Vue and other frameworks..."
    },
    "workExperience": [
      {
        "company": "ABC Technology Company",
        "position": "Frontend Engineer",
        "startDate": "2021-01",
        "endDate": "2024-12",
        "description": "Responsible for frontend development of the company's main products, using React technology stack..."
      }
    ],
    "education": [
      {
        "school": "Peking University",
        "degree": "Computer Science and Technology",
        "startDate": "2017-09",
        "endDate": "2021-06"
      }
    ],
    "skills": ["React", "Vue", "JavaScript", "TypeScript", "Node.js"]
  },
  "jobDescription": "We are looking for an experienced frontend engineer, proficient in React, Vue, JavaScript and other technologies...",
  "resumeId": "resume_123"
}

Response:

{
  "success": true,
  "analysis": {
    "overallScore": 85,
    "keywordMatchScore": 78,
    "formatScore": 92,
    "contentScore": 88,
    "sections": {
      "personalInfo": {
        "score": 95,
        "issues": [],
        "suggestions": []
      },
      "workExperience": {
        "score": 85,
        "issues": ["Work description lacks specific technical achievements"],
        "suggestions": ["Add specific project results and metrics", "Use more job-related keywords"]
      },
      "skills": {
        "score": 90,
        "issues": [],
        "suggestions": ["Can add more job-related skills"]
      }
    },
    "extractedKeywords": ["React", "Vue", "JavaScript", "frontend", "development"],
    "matchedKeywords": ["React", "Vue", "JavaScript"],
    "missingKeywords": ["TypeScript", "Webpack", "Git"],
    "keywordDensity": {
      "React": 0.15,
      "Vue": 0.1,
      "JavaScript": 0.12
    },
    "suggestions": [
      {
        "type": "keyword",
        "priority": "high",
        "message": "Recommend adding 'TypeScript' keyword in work experience",
        "section": "workExperience"
      },
      {
        "type": "content",
        "priority": "medium",
        "message": "Work description can be more specific, add project results and data",
        "section": "workExperience"
      },
      {
        "type": "format",
        "priority": "low",
        "message": "Recommend using more standard date format",
        "section": "workExperience"
      }
    ],
    "compatibilityInsights": {
      "atsReadability": "excellent",
      "formatCompatibility": "good",
      "keywordOptimization": "needs_improvement"
    }
  }
}

🤖 AI Content Generation

Endpoint: POST /api/ai/generate

Description: Use AI to generate or optimize resume content

Authentication: Required login

Request Body:

{
  "type": "work_experience",
  "context": {
    "position": "Frontend Engineer",
    "company": "ABC Technology Company",
    "duration": "3 years",
    "technologies": ["React", "Vue", "JavaScript"],
    "achievements": ["Improved page performance", "Developed component library"]
  },
  "jobDescription": "Responsible for frontend development work, requires React experience...",
  "tone": "professional",
  "language": "zh-cn"
}

Supported Content Types:

  • personal_summary: Personal summary
  • work_experience: Work experience description
  • project_description: Project description
  • skills_summary: Skills summary
  • cover_letter: Cover letter

Response:

{
  "success": true,
  "data": {
    "generatedContent": "During my time as a Frontend Engineer at ABC Technology Company, I was responsible for the frontend development of the company's core products. Proficient in using modern frontend frameworks such as React and Vue, I successfully developed multiple high-performance user interfaces. By optimizing code structure and implementing best practices, I improved page loading speed by 40%. I also led the development of the company's component library system, improving team development efficiency by 30% and saving significant development costs for the company.",
    "keywordIntegration": {
      "integrated": ["React", "Vue", "frontend development", "performance optimization"],
      "density": 0.08,
      "naturalness": "high"
    },
    "alternatives": [
      {
        "version": "Concise Version",
        "content": "Responsible for frontend development at ABC Technology Company, built user interfaces using React, Vue, improved performance by 40%, developed component library to improve team efficiency by 30%."
      },
      {
        "version": "Detailed Version",
        "content": "As a senior frontend engineer at ABC Technology Company, I focused on user experience and technological innovation during my 3 years of work..."
      }
    ],
    "metrics": {
      "readabilityScore": 88,
      "professionalTone": 92,
      "keywordRelevance": 85
    }
  }
}

🎨 Theme Recommendation

Endpoint: POST /api/ai/theme-recommendation

Description: Recommend the most suitable template themes based on resume content and target position

Authentication: Required login

Request Body:

{
  "resumeData": {
    /* Resume data */
  },
  "targetRole": "Frontend Engineer",
  "industry": "Technology",
  "experience": "mid-level",
  "preferences": {
    "style": "modern",
    "colorPreference": "blue",
    "layout": "single-column"
  }
}

Response:

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "templateId": "template_123",
        "templateName": "Modern Tech",
        "confidence": 0.92,
        "reasoning": "The modern design style and technical feel of this template is perfect for frontend engineer positions",
        "pros": ["Clean modern design style", "Highlights technical skills display", "Good ATS compatibility"],
        "cons": ["May be too modern for traditional industries"],
        "customizations": {
          "primaryColor": "#2563eb",
          "fontFamily": "Inter",
          "layout": "two-column"
        }
      },
      {
        "templateId": "template_456",
        "templateName": "Professional Minimal",
        "confidence": 0.85,
        "reasoning": "Professional layout suitable for experienced developers, highlights work achievements",
        "pros": ["Professional visual presentation", "Suitable for mid-to-senior positions", "Good content organization"],
        "cons": ["Relatively conservative design"]
      }
    ],
    "styleAnalysis": {
      "recommendedStyle": "modern-professional",
      "colorScheme": "tech-blue",
      "layoutPreference": "two-column",
      "fontRecommendation": "sans-serif"
    },
    "industryInsights": {
      "popularStyles": ["modern", "minimal"],
      "colorTrends": ["blue", "gray", "green"],
      "layoutPreferences": ["two-column", "single-column"]
    }
  }
}

📝 Usage Examples

JavaScript Example

// ATS Analysis
async function analyzeResume(resumeData, jobDescription, resumeId) {
  const response = await fetch('/api/ai/analyze', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      resumeData,
      jobDescription,
      resumeId
    })
  })
 
  const data = await response.json()
  if (data.success) {
    return data.analysis
  } else {
    throw new Error(data.error)
  }
}
 
// AI Content Generation
async function generateContent(type, context, jobDescription) {
  const response = await fetch('/api/ai/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      type,
      context,
      jobDescription,
      tone: 'professional',
      language: 'zh-cn'
    })
  })
 
  const data = await response.json()
  if (data.success) {
    return data.data
  } else {
    throw new Error(data.error)
  }
}
 
// Theme Recommendation
async function getThemeRecommendations(resumeData, targetRole, industry) {
  const response = await fetch('/api/ai/theme-recommendation', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      resumeData,
      targetRole,
      industry,
      experience: 'mid-level'
    })
  })
 
  const data = await response.json()
  if (data.success) {
    return data.data
  } else {
    throw new Error(data.error)
  }
}

React Hook Example

import { useState } from 'react'
 
function useAIAnalysis() {
  const [analysis, setAnalysis] = useState(null)
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState(null)
 
  const analyzeResume = async (resumeData, jobDescription, resumeId) => {
    try {
      setLoading(true)
      setError(null)
 
      const response = await fetch('/api/ai/analyze', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        credentials: 'include',
        body: JSON.stringify({
          resumeData,
          jobDescription,
          resumeId
        })
      })
 
      const data = await response.json()
      if (data.success) {
        setAnalysis(data.analysis)
        return data.analysis
      } else {
        throw new Error(data.error)
      }
    } catch (err) {
      setError(err.message)
      throw err
    } finally {
      setLoading(false)
    }
  }
 
  return {
    analysis,
    loading,
    error,
    analyzeResume
  }
}
 
// AI Analysis Results Component
function AIAnalysisResults({ analysis }) {
  if (!analysis) return null
 
  return (
    <div className="ai-analysis-results">
      <div className="overall-score">
        <h3>Overall Score</h3>
        <div className="score-circle">
          <span className="score">{analysis.overallScore}</span>
          <span className="total">/100</span>
        </div>
      </div>
 
      <div className="score-breakdown">
        <h4>Score Details</h4>
        <div className="score-item">
          <span>Keyword Match</span>
          <span>{analysis.keywordMatchScore}/100</span>
        </div>
        <div className="score-item">
          <span>Format Compliance</span>
          <span>{analysis.formatScore}/100</span>
        </div>
        <div className="score-item">
          <span>Content Quality</span>
          <span>{analysis.contentScore}/100</span>
        </div>
      </div>
 
      <div className="suggestions">
        <h4>Optimization Suggestions</h4>
        {analysis.suggestions.map((suggestion, index) => (
          <div key={index} className={`suggestion ${suggestion.priority}`}>
            <span className="priority">{suggestion.priority}</span>
            <span className="message">{suggestion.message}</span>
          </div>
        ))}
      </div>
 
      <div className="keywords">
        <h4>Keyword Analysis</h4>
        <div className="keyword-section">
          <h5>Matched Keywords</h5>
          <div className="keyword-list matched">
            {analysis.matchedKeywords.map((keyword) => (
              <span key={keyword} className="keyword">
                {keyword}
              </span>
            ))}
          </div>
        </div>
        <div className="keyword-section">
          <h5>Missing Keywords</h5>
          <div className="keyword-list missing">
            {analysis.missingKeywords.map((keyword) => (
              <span key={keyword} className="keyword">
                {keyword}
              </span>
            ))}
          </div>
        </div>
      </div>
    </div>
  )
}

AI Content Generation Example

function useAIContentGeneration() {
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState(null)
 
  const generateWorkExperience = async (context, jobDescription) => {
    try {
      setLoading(true)
      setError(null)
 
      const response = await fetch('/api/ai/generate', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        credentials: 'include',
        body: JSON.stringify({
          type: 'work_experience',
          context,
          jobDescription,
          tone: 'professional',
          language: 'zh-cn'
        })
      })
 
      const data = await response.json()
      if (data.success) {
        return data.data
      } else {
        throw new Error(data.error)
      }
    } catch (err) {
      setError(err.message)
      throw err
    } finally {
      setLoading(false)
    }
  }
 
  const generatePersonalSummary = async (context, jobDescription) => {
    try {
      setLoading(true)
 
      const response = await fetch('/api/ai/generate', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        credentials: 'include',
        body: JSON.stringify({
          type: 'personal_summary',
          context,
          jobDescription,
          tone: 'professional',
          language: 'zh-cn'
        })
      })
 
      const data = await response.json()
      if (data.success) {
        return data.data
      } else {
        throw new Error(data.error)
      }
    } catch (err) {
      setError(err.message)
      throw err
    } finally {
      setLoading(false)
    }
  }
 
  return {
    loading,
    error,
    generateWorkExperience,
    generatePersonalSummary
  }
}

❌ Error Handling

Common Error Codes

Error CodeHTTP StatusDescription
AI_SERVICE_UNAVAILABLE503AI service temporarily unavailable
INVALID_RESUME_DATA400Invalid resume data format
JOB_DESCRIPTION_TOO_SHORT400Job description too short
CONTENT_GENERATION_FAILED500Content generation failed
ANALYSIS_QUOTA_EXCEEDED429Analysis quota exceeded
UNSUPPORTED_LANGUAGE400Unsupported language

Error Response Example

{
  "error": "AI service temporarily unavailable, please try again later",
  "code": "AI_SERVICE_UNAVAILABLE",
  "details": {
    "service": "ats_analyzer",
    "retryAfter": 300
  }
}

🚦 Usage Limits

Request Rate Limits

Subscription TypeATS AnalysisContent GenerationTheme Recommendation
FREE3 times/day5 times/day2 times/day
PREMIUM50 times/month100 times/month20 times/month
ENTERPRISEUnlimitedUnlimitedUnlimited

Content Limits

  • Resume Content: Maximum 50KB
  • Job Description: Maximum 10KB
  • Generated Content: Maximum 5KB
  • Analysis Report: Maximum 1MB

Next Steps

🔗 Webhooks

Learn how to use Webhooks to receive real-time notifications

View Webhooks →

💡 Example Code

Browse complete code examples and best practices

View Example Code →

Need help?Contact us for support

Getting StartedUser GuideSupport

Last updated: 12/30/2024 •Suggest improvements