{ "openapi": "3.0.0", "info": { "title": "点数体系", "version": "", "termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api", "contact": { "email": "YouCamOnlineEditor_API@perfectcorp.com" }, "license": { "name": "Privacy policy", "url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api" }, "description": "查询点数明细与使用记录。请注意，Units 是 YouCam API 的计费单位，不同 AI 功能扣减的点数各不相同。本文档中点数的代号为 \"Credit\"。\n" }, "servers": [ { "url": "https://yce-api-01.makeupar.com" } ], "paths": { "/s2s/v1.0/client/credit": { "get": { "summary": "查询点数信息", "description": "以两位小数显示可用点数", "security": [ { "BearerAuthentication": [] } ], "responses": { "200": { "description": "成功获取点数信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "响应状态", "example": 200 }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "该项点数的唯一标识", "example": 13105541279084536 }, "type": { "type": "string", "enum": [ "ApiSubsToken", "ApiPaygToken" ], "description": "该项点数的类型" }, "amount": { "deprecated": true, "type": "integer", "description": "此参数已弃用，请改用 amount_dec。当前点数余额。", "example": 10 }, "amount_dec": { "type": "number", "description": "以两位小数显示的剩余点数。", "example": 10.04 }, "expiry": { "type": "integer", "description": "该项点数的到期时间（Unix 时间戳，毫秒）", "example": 1704789135000 } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/s2s/v1.0/client/credit/history": { "get": { "summary": "查看点数记录", "security": [ { "BearerAuthentication": [] } ], "parameters": [ { "name": "page_size", "in": "query", "schema": { "type": "integer", "example": 20 }, "description": "每页返回的条目数量，取值 1 到 30，默认 20。" }, { "name": "starting_token", "in": "query", "schema": { "type": "string", "example": "73a3c9e69b89" }, "description": "本页的起始 token。第一页传 `null`， 之后用上一次响应里的 `next_token` 作为下一页的起点" } ], "responses": { "200": { "description": "成功获取点数使用记录", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 200, "description": "响应状态" }, "result": { "type": "object", "properties": { "next_token": { "type": "string", "example": "73a3c9e69b89", "description": "用于查询下一页的 token。" }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 38173479337460984, "description": "该条记录的唯一标识" }, "timestamp": { "type": "integer", "example": 1703146067000, "description": "该条记录的时间（Unix 时间戳，毫秒）" }, "action": { "type": "string", "example": "photo_enhance", "enum": [ "photo_enhance", "api_photo_enhance", "object_removal", "api_object_removal", "background_removal", "api_background_removal", "colorize", "api_colorize", "text_to_image", "api_text_to_image", "hair_style", "api_hair_style", "blur_background", "change_background", "wig", "trial_gift_text_to_image", "sign_up_gift", "subscription_credits", "subscriber_gift", "permanent_credits", "compensation_from_customer_service", "renew", "expire" ], "description": "该条记录对应的操作" }, "target_id": { "type": "string", "example": "7TWFkuE2Z9uR0NOxSmQ1rh4PJ5Zx7YJ5U9SAz51q0QHVwMP+Jb1XbjPsf7ZgUgLY", "description": "该笔点数对应的对象 ID。例如运行 AI 照片优化任务时， 这条记录的 `target_id` 就是该 AI 照片优化任务的 `task_id`； 购买点数时，这条记录的 `target_id` 是 `order_id`。" }, "info": { "type": "object", "properties": { "credits": { "type": "array", "example": [ { "id": 24409059381740548, "amount": -2 }, { "id": 27297116883780870, "amount": 0 } ], "description": "每一项点数的详细信息", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "点数 ID" }, "amount": { "deprecated": true, "type": "integer", "description": "此参数已弃用，请改用 amount_dec。该项点数的变动总量。" }, "amount_dec": { "type": "number", "description": "本次记录的点数净变化，以两位小数显示。" } } } }, "dst_actions": { "type": "array", "description": "AI 肤质分析要输出的项目（dst_actions）", "items": { "type": "string" }, "example": "[ \"hd_wrinkle\", \"hd_pore\", \"hd_texture\" ]" } } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/InvalidParameters" }, "401": { "$ref": "#/components/responses/InvalidAccessToken" } } } }, "/s2s/v2.0/credit/feature-cost": { "get": { "summary": "查询功能花费", "description": "查询各接口的点数消耗。数值与 https://yce.perfectcorp.com/ai-api/api-pricing 列出的一致。", "security": [ { "BearerAuthenticationV2": [] } ], "parameters": [ { "name": "page_size", "in": "query", "schema": { "type": "integer", "example": 20, "minimum": 1, "maximum": 20 }, "description": "每页返回的条目数量，默认 20，取值范围 [1 - 20]。" }, { "name": "starting_token", "in": "query", "schema": { "type": "string", "example": "MjA" }, "description": "本页的起始 token。第一页传 `null`， 之后用上一次响应里的 `next_token` 作为下一页的起点" } ], "responses": { "200": { "description": "成功按 sku 获取功能花费", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 200, "description": "响应状态" }, "result": { "type": "object", "properties": { "next_token": { "type": "string", "example": "MjA", "description": "查询下一页的 token。没有更多页时为 `null`。" }, "skus": { "type": "array", "description": "sku 列表", "items": { "type": "object", "properties": { "description": { "type": "string", "example": "AI Skin Analysis for SD 1~4 concerns", "description": "该 sku 的说明" }, "amount": { "type": "number", "example": 9, "description": "每个 `proc_unit` 消耗的点数" }, "unit": { "type": "string", "enum": [ "result_image", "second" ], "example": "result_image", "description": "花费的计量单位" }, "proc_unit": { "type": "integer", "example": 1, "description": "一笔 `amount` 扣减所包含的 `unit` 数量。" }, "run_task_url": { "type": "string", "example": "https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis", "description": "消耗此 SKU 的任务接口完整 URL。" } } } } } } } }, "example": { "status": 200, "result": { "next_token": "MjA", "skus": [ { "description": "AI 肤质分析（SD 第 1~4 项）", "amount": 9, "unit": "result_image", "proc_unit": 1, "run_task_url": "https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis" }, { "description": "AI 肤质分析（SD 第 5~7 项）", "amount": 12, "unit": "result_image", "proc_unit": 1, "run_task_url": "https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis" } ] } } } } }, "400": { "$ref": "#/components/responses/InvalidParameters" }, "401": { "$ref": "#/components/responses/InvalidApiKey" } } } } }, "components": { "securitySchemes": { "BearerAuthentication": { "type": "http", "scheme": "bearer", "description": "使用鉴权得到的 `access_token`，并把它放进请求头： `Authorization:Bearer `" }, "BearerAuthenticationV2": { "type": "http", "scheme": "bearer", "description": "使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。" } }, "responses": { "Unauthorized": { "description": "鉴权失败，或用户缺少所需权限" }, "InvalidParameters": { "description": "请求参数无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "description": "响应状态" }, "error": { "type": "string", "example": "Invalid parameter value" }, "error_code": { "type": "string", "example": "InvalidParameters" } } } } } }, "InvalidAccessToken": { "description": "访问令牌无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "响应状态" }, "error_code": { "type": "string", "enum": [ "InvalidAccessToken" ], "description": "错误码：\n * InvalidAccessToken - 未提供 access token，或 token 无效\n" } } } } } }, "InvalidApiKey": { "description": "API 密钥无效或缺失", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "响应状态" }, "error": { "type": "string", "example": "Invalid API key" } } } } } } } } }