Media.io AI 年龄滤镜技能

概述

该技能调用 Media.io OpenAPI，使用模型代码 effects-image-age-filter 执行年龄变换。

该 API 为异步接口：

1. 提交生成请求并获取 task_id；
2. 轮询任务结果接口，直至任务完成。

适用场景

• 用户希望使人脸看起来更年长或更年轻；
• 用户可提供一个 Media.io 服务器可访问的图片 URL；
• 用户需要基于任务（task-based）的生成方式，并接受轮询机制。

不适用场景

• 用户仅要求本地文件上传（本 API 仅接受图片 URL 输入）；
• 用户指定使用非 Media.io 的服务提供商；
• 用户要求单次调用即返回实时、同步的图像输出。

前提条件

环境变量

基础请求头

• Content-Type: application/json
• X-API-KEY: $MEDIAIO_API_KEY

支持的端点

1) 查询账户余额（Credits）

• 方法：POST
• 端点：https://openapi.media.io/user/credits
• 请求体：{}
• 用途：在执行生成前检查可用余额。

2) 创建年龄滤镜任务

• 方法：POST
• 端点：https://openapi.media.io/generation/effects/effects-image-age-filter
• 请求体：

{
	"data": {
		"images": "https://example.com/input.jpg",
		"mode": "Older"
	}
}

• 必需字段：
  • data.images（字符串形式的 URL）
• 可选字段：
  • data.mode（字符串）：取值为 Older 或 Younger

3) 查询任务结果

• 方法：POST
• 端点：https://openapi.media.io/generation/result/{task_id}
• 请求体：{}
• 路径参数：
  • task_id（字符串，必需）

请求与响应契约

通用成功响应结构

{
	"code": 0,
	"msg": "",
	"data": {},
	"trace_id": "..."
}

创建任务响应

• 成功时，返回 data.task_id。

查询任务结果响应

• data.status 可能取以下值之一：
  • waiting：已入队等待处理
  • processing：正在运行中
  • completed：已成功完成
  • failed：执行失败
  • timeout：任务超时
• data.reason：提供附加上下文信息（例如 success 或具体错误消息）
• 当状态为 completed 时：
  • data.result 是一个输出对象数组，每个对象包含生成结果的 URL
  • 每个结果对象包含字段：val（内部路径）、preview（公开可访问的 HTTPS URL）和 status（完成状态）

标准调用流程

1. 调用 user/credits 接口验证账户余额；
2. 调用 effects-image-age-filter 接口，传入 data.images 及可选的 data.mode；
3. 从响应中提取 task_id；
4. 以 3 至 5 秒为间隔，轮询 generation/result/{task_id} 接口；
5. 当状态变为 completed 或 failed 时停止轮询；
6. 若状态为 completed，则从 data.result 中提取并返回输出 URL。

cURL 示例

查询余额

curl --request POST 
	--url https://openapi.media.io/user/credits 
	--header 'Content-Type: application/json' 
	--header "X-API-KEY: $MEDIAIO_API_KEY" 
	--data '{}'

创建年龄滤镜任务

curl --request POST 
	--url https://openapi.media.io/generation/effects/effects-image-age-filter 
	--header 'Content-Type: application/json' 
	--header "X-API-KEY: $MEDIAIO_API_KEY" 
	--data '{
	"data": {
		"images": "https://example.com/input.jpg",
		"mode": "Older"
	}
}'

查询任务结果

curl --request POST 
	--url https://openapi.media.io/generation/result/ 
	--header 'Content-Type: application/json' 
	--header "X-API-KEY: $MEDIAIO_API_KEY" 
	--data '{}'

成功响应示例

{
	"code": 0,
	"msg": "",
	"data": {
		"task_id": "effect-86f0f82a-36dc-4a7c-928a-721a18ef482f",
		"status": "completed",
		"reason": "success",
		"result": [
			{
				"val": "aicloudtmp/550160908/3/202603/1/combo_tm_alg-20260317165022-802800-60eb3-dwt.png",
				"preview": "https://url_to_generated_image.png",
				"status": "completed"
			}
		]
	},
	"trace_id": "a18315ba568b5c34407808d12cbc8457"
}

当 status 为 completed 时，响应字段含义如下：

• data.task_id：唯一任务标识符
• data.status：completed 表示任务已成功完成
• data.reason：success 表示未发生错误
• data.result：输出对象数组，每个对象包含：
  • val：生成资源的内部文件路径
  • preview：生成资源的公开可访问 HTTPS URL
  • status：每个结果项的状态均为 completed

错误处理指引

• 将 code != 0 视为失败响应。
• 典型的身份认证错误：
  • 374004：未通过身份认证。请前往 https://developer.media.io/ 申请 APP KEY。
• 典型的请求校验错误：
  • 490000：参数错误
• 典型的计费/余额错误：
  • 490505：余额不足。请先充值，再调用生成类 API。
• 日志中应始终记录 trace_id，以便问题排查。

智能体行为要求

• 调用创建任务接口前，须校验输入中是否包含非空的图片 URL；
• 不得在任务创建后即声称已获得输出结果；必须始终通过 task_id 进行轮询；
• 若余额不足，应返回清晰提示并终止流程，禁止无限重试；
• 避免在日志或响应中暴露原始 API 密钥。

安全与合规说明

• 仅处理用户主动提供或经用户授权的图像；
• 不得暗示生成图像具备身份核验能力或生物特征确定性；
• 生成内容属于合成媒体，应明确标注为编辑/处理后的结果。

参考资料

• Media.io 平台主页：https://developer.media.io/
• API 文档：https://platform.media.io/docs/