{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_beard_style.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_beard_style.yaml","settings":{"baseUrlPath":"/zh-cn/reference/ai_beard_style"},"disableAutoScroll":true,"seo":{"title":"AI 胡型生成器","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI 胡型生成器","version":"","description":"# 概览\nAI 男士胡须造型模拟\n\nAI 算法也照顾到男士：凭借精细的胡须模拟技术，络腮胡、短须、全须、圈须、八字胡、山羊胡等各式胡型都能自由虚拟试戴。\n\n消费者还能直接看到剃前剃后的对比，不用真拿剃刀往皮肤上招呼。\n胡须滤镜包含八字胡、短方胡、鸭尾胡、圈胡等十余种。\n\n## 接入指南\n\n1. **上传自拍**\n 源图有两种提供方式：\n\n - **使用已有的公开图片 URL**\n 不必上传，发起 AI 任务时直接给一个可公开访问的图片 URL 即可。\n\n - **通过 File 接口上传**\n 接口地址：\n ```\n POST /s2s/v2.0/file\n ```\n 这会返回一个 `file_id`，供后续执行任务时使用。\n\n - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。

\n 调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。\n\n > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n2. **获取预设风格列表**\n * 调用 /s2s/v2.0/task/template/beard-style 取得预设模板列表，挑一个 ``template_id`` 用于执行 AI 任务。\n\n3. **执行 AI 任务并取得 Task ID**\n 用 /s2s/v2.0/task/beard-style 执行 AI 任务。目标用户图请提供 ``src_file_url`` 或 ``src_file_id``，再给出要套用的风格 ``template_id``，即可取得 ``task_id``。\n\n4. **轮询任务状态，直到成功或失败**\n 用 ``task_id`` 轮询 GET /s2s/v2.0/task/beard-style 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 running，这一阶段不消耗点数。\n 您也可以实现 Webhook，在 AI 任务成功或失败时收到通知。细节见 **[Webhook](../../../develop/webhook)** 一节。\n\n > **警告：** 在任务保留期内轮询任务状态是必须做的。保留期内没有任何轮询请求，任务就会超时，即使任务已处理成功也一样，而您的点数照样会被消耗。\n\n > **警告：** 若去查询已超时任务的状态，会收到 InvalidTaskId 错误。因此，执行 AI 任务之后，必须在保留期内持续轮询，直到状态变为 success 或 error。\n\n5. **任务成功后取回结果**\n 引擎处理完您的输入文件、生成出图后，任务状态会变为 success，您会收到一张处理后图片的 URL。\n\n---\n\n## 文件规格与错误码\n * 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n|AI 胡须造型生成|分辨率：长边 < 1024
脸宽 > 256
脸部姿态：-30 < yaw < 30，
仅支持单人脸，
需露出完整脸部|< 10MB|jpg/jpeg|\n\n * 错误码\n\n|错误码|说明|\n| ---- | ---- |\n|error_no_face\t|源图中看不到脸\n|error_src_face_too_small\t|人脸过小\n|error_inference\t|胡须去除失败或胡须生成失败\n|error_face_pose\t|源图的脸部姿态不受支持\n\n * 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2
- curl >= 7.58 (modern TLS/HTTP support)
- jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 胡须造型生成 V1.0 | 2 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.126"},"lang":"zh-CN","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-cn/reference/ai_beard_style","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}