CV构建器——通过API创建简历

即刻免费创建简历、数字身份或CV。从涵盖全范围的模板中选择：经典的打印就绪PDF、简洁的HTML在线简历、交互式体验、动画3D世界以及可玩游戏。每份简历都会获得一个带有个人短链接的永久公开URL——无需注册，基础使用无需付费。适配ATS（求职者追踪系统）且符合HR（人力资源）要求。

功能概览

模板范围：经典PDF · 在线HTML · 交互式 · 3D (Three.js) · 游戏化。 完整目录：reference/templates.md— 实时预览：talent.de/de/cv-template-ideas

术语

在本技能中，以下术语始终如一地使用：

代理执行准则

必须采用人工参与流程（HITL）。您必须包含以下任一参数："prefer_hitl": true（启用人工审核）或"skip_hitl": true（直接创建）。若两者均未设置将返回400错误。当存在人类用户时，务必使用"prefer_hitl": true——该设置允许请求者自主选择URL短链、挑选模板、审核数据并在发布前予以批准。仅当处于无人工介入的自动化流程时方可使用"skip_hitl": true。

数据原则：仅使用请求方在此对话中明确提供或批准的数据。不要从未关联的系统上下文或其他会话中提取个人信息。

发送前：向请求方提供简要摘要——姓名、职位、电子邮件——并询问“发送吗？还是需要修改什么？”

领取令牌：请像对待密码一样对待它。仅与请求方共享——任何拥有此令牌的人都可以认领简历所有权。切勿与第三方共享。

凭据

一个访问ID(talent_agent_[a-z0-9]{4}) 对于简历构建器是可选的——基础使用（每个IP地址每天3份简历）无需此ID即可工作。注册以获得更高限制（每天50份简历）并支持回调网络钩子：

POST https://www.talent.de/api/agent/register
Content-Type: application/json

{ "agent_name": "my-agent" }

该访问ID也是用于验证X-HITL-Signature在回调网络钩子上的HMAC密钥。请存储在TALENT_ACCESS_ID环境变量中——请勿硬编码。

用户沟通

每个步骤需要说什么

快速开始

1. 请求（或确认您已拥有）：firstName, lastName, title, email —— 这四个必填字段
2. POST /api/agent/cv-simple附带"prefer_hitl": true以及数据可选：添加"include_pdf": true以便在最终的201响应中也收到一个base64编码的PDF文件。参见PDF导出.
3. 向请求方展示review_url（他们选择slug、模板、审核数据）
4. 轮询poll_url每30秒一次，直到"status": "completed"：
   • { "status": "pending" }或{ "status": "opened" }→ 继续轮询
   • { "status": "completed", "result": { "action": "confirm", "data": {...} } }→ 使用hitl_continue_case_id
5. 继续执行

最终批准后：展示实时简历URL和认领令牌

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "prefer_hitl": true,
  "cv_data": {
    "firstName": "Alex",
    "lastName": "Johnson",
    "title": "Software Engineer",
    "email": "alex@example.com",
    "experience": [{
      "jobTitle": "Senior Developer",
      "company": "Acme Inc.",
      "startDate": "2022-01",
      "isCurrent": true
    }],
    "hardSkills": [{ "name": "React", "level": 4 }],
    "softSkills": [{ "name": "Team Leadership" }],
    "languages": [{ "name": "English", "level": "NATIVE" }]
  }
}

示例（使用HITL — 推荐）

{
  "status": "human_input_required",
  "message": "Please confirm: is this CV for you?",
  "hitl": {
    "case_id": "review_a7f3b2c8d9e1f0g4",
    "review_url": "https://www.talent.de/en/hitl/review/review_a7f3b2c8d9e1f0g4?token=abc123...",
    "poll_url": "https://www.talent.de/api/hitl/cases/review_a7f3b2c8d9e1f0g4/status",
    "type": "confirmation",
    "inline_actions": ["confirm", "cancel"],
    "timeout": "24h"
  }
}

响应（202 — 需要人工审核）：

向请求方展示审核URL：检查你的简历你将选择你的个人URL slug、模板设计，并批准最终结果。

然后轮询poll_url直到完成，并通过hitl_continue_case_id继续执行后续步骤。

在所有步骤（确认、数据审查、slug选择、模板选择、批准）完成后，最终的POST请求将返回201状态码及实时URL。包含所有步骤、内联提交、编辑周期和升级的完整HITL协议：

reference/hitl.md

HITL多步骤流程

Step 1: Confirmation  →  "For whom is this CV?"
Step 2: Data Review   →  "Are these details correct?"
Step 3: Slug          →  Human picks personal URL slug (e.g. pro, dev, 007)
Step 4: Template      →  Human picks template design
Step 5: Approval      →  Human reviews final CV draft

请求方最多需要经历5个审查步骤。代理循环执行：呈现审查URL、轮询、继续。

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "prefer_hitl": true,
  "hitl_continue_case_id": "review_a7f3b2c8d9e1f0g4",
  "slug": "dev",
  "cv_data": { ... }
}

每个步骤返回202。在请求方做出决定后，继续执行： 重要提示：slug和template_id应位于请求的顶级层级，而不是在. 在选择 slug 后继续操作时，请在顶层包含用户选择的 slug，以便服务器知道要推进到模板步骤。

当您已经提供了值时，相关步骤会被跳过：

• 包含slug（顶层）→ slug 选择步骤被跳过
• 包含template_id（顶层）→ 模板选择步骤被跳过
• 两者都包含 → 仅剩下确认、数据审查和批准步骤

内联提交 (v0.7)

对于简单的决策（确认、升级、批准），202 响应中包含submit_url、submit_token和inline_actions. 代理可以通过Bearer令牌直接提交——这适用于支持按钮的Telegram、Slack、WhatsApp等平台：

POST {submit_url}
Authorization: Bearer {submit_token}
Content-Type: application/json

{ "action": "confirm", "data": {} }

始终提供review_url作为备用方案，与任何内联按钮一同提供。如果平台不支持按钮（如短信、电子邮件、纯文本），或者用户更倾向于使用浏览器，他们可以使用链接来完成决策。

选择和输入类型始终需要浏览器（review_url）——因为它们涉及复杂的用户界面（如模板网格、数据表单）。完整的内联规范：reference/hitl.md

在最终批准步骤后，使用hitl_approved_case_id提交以发布：

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "hitl_approved_case_id": "review_final_case_id"
}

响应（201）：

{
  "success": true,
  "url": "https://www.talent.de/dev/alex-johnson",
  "cv_id": "cv_abc123",
  "claim_token": "claim_xyz789",
  "template_id": "007",
  "quality_score": 65,
  "quality_label": "good",
  "improvement_suggestions": []
}

⚠️收到201响应后——务必立即与请求方分享以下两者：

1. 简历URL：https://www.talent.de/dev/alex-johnson— 他们的在线个人资料
2. 认领链接：https://www.talent.de/claim/claim_xyz789— 用于获取所有权并进行编辑

该认领令牌是永久性的，永不过期。请像对待密码一样保管它——仅与请求者分享。

呈现结果：

您的简历已上线：talent.de/dev/alex-johnson

要认领所有权并编辑您的简历，请访问：talent.de/claim/claim_xyz789请妥善保管此链接——它永不过期，并授予完全编辑权限。

如果响应中包含改进建议，请与请求者分享并提供更新简历的服务：

您的简历评分为 35/100。要提升评分，我可以添加：工作经验（+25分）、专业概述（+20分）。您希望我向您提几个问题并更新简历吗？

代理循环（可视化）

以下两条路径——包含人工审核与不包含人工审核——均已展示如下。请每个请求选择其一。

flowchart TD
    START([Agent starts]) --> CHOICE{prefer_hitl\nor skip_hitl?}

    %% ── skip_hitl path ──────────────────────────────────────────
    CHOICE -->|skip_hitl: true| DIRECT["POST /api/agent/cv-simple\nskip_hitl: true + cv_data"]
    DIRECT --> D201["201 — CV live\nurl · claim_token · quality_score\nimprovement_suggestions"]
    D201 --> SHARE_NOW["Share url + claim_token\nwith requestor immediately!"]
    SHARE_NOW --> QUAL{improvement_suggestions\npresent AND attempt < 2?}
    QUAL -->|No / attempt >= 2| DONE_DIRECT([Done])
    QUAL -->|Yes| ASK["Ask requestor the questions\nin each agent_action field"]
    ASK --> REPOST["POST /api/agent/cv-simple\nskip_hitl: true\nenriched cv_data\n(new cv_id each time)"]
    REPOST --> D201

    %% ── prefer_hitl path ─────────────────────────────────────────
    CHOICE -->|prefer_hitl: true| HITL["POST /api/agent/cv-simple\nprefer_hitl: true + cv_data"]
    HITL --> H202["202 human_input_required\nreview_url · poll_url · events_url"]
    H202 --> SHOW_URL["Present review_url to requestor\n'Please review here: [link]'"]
    SHOW_URL --> POLL["Poll poll_url every 30s\n(or use events_url for SSE)"]
    POLL --> STATUS{status?}
    STATUS -->|pending / opened\n/ in_progress| POLL
    STATUS -->|completed| ACTION{result.action?}
    STATUS -->|expired| EXP{default_action?}
    STATUS -->|cancelled| CANCELLED([Inform requestor: cancelled])

    EXP -->|skip| AUTO_PUB["CV auto-published\nurl from poll status"]
    EXP -->|abort| ABORTED([Inform requestor: expired])

    ACTION -->|confirm / select| CONTINUE["POST cv-simple\nhitl_continue_case_id\n+ ALWAYS include cv_data"]
    ACTION -->|edit| EDIT["Adjust cv_data per note\nthen CONTINUE"]
    EDIT --> CONTINUE
    ACTION -->|reject| REJECT["Escalation step\nPOST hitl_continue_case_id"]
    REJECT --> H202
    ACTION -->|approve| PUBLISH["POST cv-simple\nhitl_approved_case_id + cv_data"]
    CONTINUE --> H202
    PUBLISH --> DONE_HITL(["201 — CV live\nShare url + claim_token"])

当一个人机交互任务案例过期时，服务器将执行为该步骤配置的默认操作

• ：跳过：简历将自动发布，使用服务器选择的标识/模板。轮询轮询网址——它将返回状态："已完成"，并在结果中包含网址
• 。中止：流程终止。通知请求方会话已过期。如需，使用prefer_hitl: true

开始一个新的人机交互流程。

质量改进循环（skip_hitl）在任何201响应之后，简历将立即生效。务必共享网址和首先与请求者沟通。

如果improvement_suggestions非空，你可以选择性地运行最多2个改进周期：

1. 对于每个建议：向请求者提出agent_action
2. 中的确切问题。重新提交，附带增强的cv_data和
3. skip_hitl: true每次重新提交都会创建一个新的简历，并附带一个新的cv_id
4. ——之前的简历将被废弃。在2个周期后或当improvement_suggestions为空时：

停止一个持续重复提交的代理会导致重复的简历并浪费请求者的时间。

对于prefer_hitl流程：在审批之后，201响应已经过质量评估（数据已通过人工审核）。如果出现建议，直接询问请求者——不要重启HITL流程。

直接创建（无人工介入）

对于完全自动化的流水线、批量操作，或者当请求者明确表示"直接创建"时——设置"skip_hitl": true：

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "skip_hitl": true,
  "cv_data": {
    "firstName": "Alex",
    "lastName": "Johnson",
    "title": "Software Engineer",
    "email": "alex@example.com"
  }
}

响应（201）：

{
  "success": true,
  "url": "https://www.talent.de/pro/alex-johnson",
  "cv_id": "cv_abc123",
  "claim_token": "claim_xyz789",
  "template_id": "018",
  "hitl_skipped": true,
  "quality_score": 20,
  "quality_label": "basic",
  "improvement_suggestions": [
    {
      "field": "experience",
      "issue": "No work experience — CV has low ATS compatibility",
      "agent_action": "Ask: 'What positions have you held? Part-time and internships count.'",
      "impact": "+25 quality points",
      "priority": "high"
    }
  ],
  "next_steps": "Share improvement_suggestions with the requestor and ask the questions in agent_action. Then update the CV via POST /api/agent/cv-simple...",
  "auto_fixes": []
}

在直接模式下，服务器会自动分配slug（pro作为默认值）和模板（018Amber Horizon）。请求者没有选择权。仅在无需人工审核时使用此模式。

你必须选择其一： "prefer_hitl": true或"skip_hitl": true。两者都省略将返回400错误。

除四个必填字段外，所有其他字段均为可选。没有的内容请直接省略——不要发送空数组。

PDF导出

获取可下载的PDF版本简历。提供三种视觉主题：

方案A：在创建简历时同步生成

在请求中添加"include_pdf": true响应将包含Base64编码的PDF文件：

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "prefer_hitl": true,
  "include_pdf": true,
  "pdf_format": "A4",
  "pdf_theme": "modern",
  "cv_data": {
    "firstName": "Alex",
    "lastName": "Johnson",
    "title": "Software Engineer",
    "email": "alex@example.com"
  }
}

响应包含pdf对象：

{
  "success": true,
  "url": "https://www.talent.de/pro/alex-johnson",
  "cv_id": "cv_abc123",
  "claim_token": "claim_xyz789",
  "pdf": {
    "base64": "JVBERi0xLjQK...",
    "size_bytes": 6559,
    "generation_ms": 226,
    "format": "A4"
  }
}

选项B：为现有简历生成PDF

POST https://www.talent.de/api/agent/cv/pdf
Content-Type: application/json

{
  "cv_id": "cv_abc123",
  "format": "A4",
  "theme": "minimal"
}

直接返回PDF二进制数据（内容类型：application/pdf）。格式选项：A4（默认），LETTER。主题选项：classic（默认），modern，minimal。

PDF生成耗时约200毫秒（无需无头浏览器）。

服务器端智能处理

您无需检查slug可用性或验证数据——服务器会处理这些：

• Slug唯一性：Slug并非全局唯一——它仅对个人唯一。pro/thomas-mueller和pro/anna-schmidt可以共存。只有 "slug + 名 + 姓" 的组合是保留的。这就是为什么服务器需要先获取姓名来检查可用性。
• Slug 自动选择：如果省略（且未启用 HITL），服务器会默认选择pro。如果该 slug 已用于此人的姓名，它会自动尝试下一个可用的 slug。在 HITL 模式下，用户可以交互式地选择他们的 slug。常见选择（摘录）：007·911·dev·api·pro·gpt·web·ceo·cto·ops·f40·gtr·amg·gt3·zen·art·lol·neo·404·777。完整列表：GET /api/public/slugs
• 默认模板：018（琥珀地平线），如果省略。
• 日期标准化：2024变成2024-01-01，2024-03变成2024-03-01。
• 语言级别：已标准化为CEFR（母语水平、C2、C1、B2、B1、A2、A1）。
• 可读错误提示：如果出现问题，响应会以通俗易懂的英语解释需要修复的内容。
• 自动修复摘要：该自动修复数组会告诉你服务器调整了什么（例如：“此名称的Slug 'pro'已被占用，改为使用'dev'”）。

技能使用4个数组

• 硬技能— 技术技能，可选等级1-5
• 软技能— 仅名称
• 工具技能— 仅名称
• 语言— 附带CEFR等级等级：母语、C2、C1、B2、B1、A2、A1

不要使用通用的技能数组——它会被忽略。常见错误

错误示例

护栏机制

• 速率限制（使用Access-ID）：50份简历/天
• 速率限制（无Access-ID）：每个IP 3份简历/天
• 未经请求者批准绝不自动提交
• 申领令牌是永久性的 — 请视为密码对待

参考资料

• 简历数据参考：所有字段及其约束条件，适用于简历数据
• 模板：包含预览的完整模板目录
• 人机交互协议人机协同审核流程（全步骤、内联提交、编辑周期）
• 访问系统：速率限制与访问ID注册
• 错误代码：错误参考与故障排除
• 隐私：数据处理与GDPR合规

规范

• agent.json
• hitl.json
• llms.txt
• ClawHub