文档

AI 服务 API

SmartCV AI 服务 API 文档，包含 ATS 分析、智能优化、主题推荐等 AI 功能

更新时间: 2024/12/30

SmartCV AI 服务提供强大的人工智能功能，包括 ATS 兼容性分析、智能简历优化、主题推荐等。

📋 API 端点概览

端点方法描述
/api/ai/analyzePOSTATS 兼容性分析
/api/ai/generatePOSTAI 内容生成
/api/ai/theme-recommendationPOST主题推荐

🔍 ATS 兼容性分析

端点: POST /api/ai/analyze

描述: 分析简历与职位描述的匹配度，提供 ATS 兼容性评分和优化建议

认证: 需要登录

请求体:

{
  "resumeData": {
    "personalInfo": {
      "name": "张三",
      "email": "[email protected]",
      "phone": "13800138000",
      "summary": "5年前端开发经验，熟练掌握React、Vue等框架..."
    },
    "workExperience": [
      {
        "company": "ABC科技公司",
        "position": "前端工程师",
        "startDate": "2021-01",
        "endDate": "2024-12",
        "description": "负责公司主要产品的前端开发，使用React技术栈..."
      }
    ],
    "education": [
      {
        "school": "北京大学",
        "degree": "计算机科学与技术",
        "startDate": "2017-09",
        "endDate": "2021-06"
      }
    ],
    "skills": ["React", "Vue", "JavaScript", "TypeScript", "Node.js"]
  },
  "jobDescription": "我们正在寻找一位经验丰富的前端工程师，要求熟练掌握React、Vue、JavaScript等技术...",
  "resumeId": "resume_123"
}

响应:

{
  "success": true,
  "analysis": {
    "overallScore": 85,
    "keywordMatchScore": 78,
    "formatScore": 92,
    "contentScore": 88,
    "sections": {
      "personalInfo": {
        "score": 95,
        "issues": [],
        "suggestions": []
      },
      "workExperience": {
        "score": 85,
        "issues": ["工作描述中缺少具体的技术成果"],
        "suggestions": ["添加具体的项目成果和数据指标", "使用更多与职位相关的关键词"]
      },
      "skills": {
        "score": 90,
        "issues": [],
        "suggestions": ["可以添加更多与职位相关的技能"]
      }
    },
    "extractedKeywords": ["React", "Vue", "JavaScript", "前端", "开发"],
    "matchedKeywords": ["React", "Vue", "JavaScript"],
    "missingKeywords": ["TypeScript", "Webpack", "Git"],
    "keywordDensity": {
      "React": 0.15,
      "Vue": 0.1,
      "JavaScript": 0.12
    },
    "suggestions": [
      {
        "type": "keyword",
        "priority": "high",
        "message": "建议在工作经历中添加 'TypeScript' 关键词",
        "section": "workExperience"
      },
      {
        "type": "content",
        "priority": "medium",
        "message": "工作描述可以更具体，添加项目成果和数据",
        "section": "workExperience"
      },
      {
        "type": "format",
        "priority": "low",
        "message": "建议使用更标准的日期格式",
        "section": "workExperience"
      }
    ],
    "compatibilityInsights": {
      "atsReadability": "excellent",
      "formatCompatibility": "good",
      "keywordOptimization": "needs_improvement"
    }
  }
}

🤖 AI 内容生成

端点: POST /api/ai/generate

描述: 使用 AI 生成或优化简历内容

认证: 需要登录

请求体:

{
  "type": "work_experience",
  "context": {
    "position": "前端工程师",
    "company": "ABC科技公司",
    "duration": "3年",
    "technologies": ["React", "Vue", "JavaScript"],
    "achievements": ["提升页面性能", "开发组件库"]
  },
  "jobDescription": "负责前端开发工作，要求有React经验...",
  "tone": "professional",
  "language": "zh-cn"
}

支持的内容类型:

  • personal_summary: 个人简介
  • work_experience: 工作经历描述
  • project_description: 项目描述
  • skills_summary: 技能总结
  • cover_letter: 求职信

响应:

{
  "success": true,
  "data": {
    "generatedContent": "在ABC科技公司担任前端工程师期间，我负责公司核心产品的前端开发工作。熟练运用React、Vue等现代前端框架，成功开发了多个高性能的用户界面。通过优化代码结构和实施最佳实践，将页面加载速度提升了40%。同时主导开发了公司的组件库系统，提高了团队开发效率30%，为公司节省了大量开发成本。",
    "keywordIntegration": {
      "integrated": ["React", "Vue", "前端开发", "性能优化"],
      "density": 0.08,
      "naturalness": "high"
    },
    "alternatives": [
      {
        "version": "简洁版",
        "content": "负责ABC科技公司前端开发，使用React、Vue构建用户界面，优化性能提升40%，开发组件库提高团队效率30%。"
      },
      {
        "version": "详细版",
        "content": "作为ABC科技公司的资深前端工程师，我在3年的工作期间专注于用户体验和技术创新..."
      }
    ],
    "metrics": {
      "readabilityScore": 88,
      "professionalTone": 92,
      "keywordRelevance": 85
    }
  }
}

🎨 主题推荐

端点: POST /api/ai/theme-recommendation

描述: 基于简历内容和目标职位推荐最适合的模板主题

认证: 需要登录

请求体:

{
  "resumeData": {
    /* 简历数据 */
  },
  "targetRole": "前端工程师",
  "industry": "科技",
  "experience": "mid-level",
  "preferences": {
    "style": "modern",
    "colorPreference": "blue",
    "layout": "single-column"
  }
}

响应:

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "templateId": "template_123",
        "templateName": "现代科技",
        "confidence": 0.92,
        "reasoning": "该模板的现代设计风格和技术感非常适合前端工程师职位",
        "pros": ["简洁现代的设计风格", "突出技术技能展示", "良好的 ATS 兼容性"],
        "cons": ["对于传统行业可能过于现代"],
        "customizations": {
          "primaryColor": "#2563eb",
          "fontFamily": "Inter",
          "layout": "two-column"
        }
      },
      {
        "templateId": "template_456",
        "templateName": "专业简约",
        "confidence": 0.85,
        "reasoning": "专业的布局适合有经验的开发者，突出工作成果",
        "pros": ["专业的视觉呈现", "适合中高级职位", "良好的内容组织"],
        "cons": ["设计相对保守"]
      }
    ],
    "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"]
    }
  }
}

📝 使用示例

JavaScript 示例

// ATS 分析
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 内容生成
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)
  }
}
 
// 主题推荐
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 示例

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 分析结果组件
function AIAnalysisResults({ analysis }) {
  if (!analysis) return null
 
  return (
    <div className="ai-analysis-results">
      <div className="overall-score">
        <h3>总体评分</h3>
        <div className="score-circle">
          <span className="score">{analysis.overallScore}</span>
          <span className="total">/100</span>
        </div>
      </div>
 
      <div className="score-breakdown">
        <h4>评分详情</h4>
        <div className="score-item">
          <span>关键词匹配</span>
          <span>{analysis.keywordMatchScore}/100</span>
        </div>
        <div className="score-item">
          <span>格式规范</span>
          <span>{analysis.formatScore}/100</span>
        </div>
        <div className="score-item">
          <span>内容质量</span>
          <span>{analysis.contentScore}/100</span>
        </div>
      </div>
 
      <div className="suggestions">
        <h4>优化建议</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>关键词分析</h4>
        <div className="keyword-section">
          <h5>已匹配关键词</h5>
          <div className="keyword-list matched">
            {analysis.matchedKeywords.map((keyword) => (
              <span key={keyword} className="keyword">
                {keyword}
              </span>
            ))}
          </div>
        </div>
        <div className="keyword-section">
          <h5>缺失关键词</h5>
          <div className="keyword-list missing">
            {analysis.missingKeywords.map((keyword) => (
              <span key={keyword} className="keyword">
                {keyword}
              </span>
            ))}
          </div>
        </div>
      </div>
    </div>
  )
}

AI 内容生成示例

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
  }
}

❌ 错误处理

常见错误码

错误码HTTP 状态描述
AI_SERVICE_UNAVAILABLE503AI 服务暂不可用
INVALID_RESUME_DATA400简历数据格式错误
JOB_DESCRIPTION_TOO_SHORT400职位描述过短
CONTENT_GENERATION_FAILED500内容生成失败
ANALYSIS_QUOTA_EXCEEDED429分析次数超限
UNSUPPORTED_LANGUAGE400不支持的语言

错误响应示例

{
  "error": "AI 服务暂时不可用，请稍后重试",
  "code": "AI_SERVICE_UNAVAILABLE",
  "details": {
    "service": "ats_analyzer",
    "retryAfter": 300
  }
}

🚦 使用限制

请求频率限制

订阅类型ATS 分析内容生成主题推荐
FREE3次/天5次/天2次/天
PREMIUM50次/月100次/月20次/月
ENTERPRISE无限制无限制无限制

内容限制

  • 简历内容: 最大 50KB
  • 职位描述: 最大 10KB
  • 生成内容: 最大 5KB
  • 分析报告: 最大 1MB

下一步

🔗 Webhooks

了解如何使用 Webhooks 接收实时通知

查看 Webhooks →

💡 示例代码

浏览完整的代码示例和最佳实践

查看示例代码 →

遇到问题？联系我们获取帮助

快速入门用户指南技术支持

最后更新: 2024/12/30 •改进建议