--- name: mediaio-ai-gender-swap description: 通过 Media.io OpenAPI 调用 AI，将照片与图像转换为吉卜力工作室（Studio Ghibli）风格的艺术作品。应用吉卜力电影标志性的手绘感与绘画式美学。支持 AI 性别转换、AI 性别变换、男性转女性 AI。 metadata: {"openclaw": {"homepage": "https://platform.media.io/docs/", "requires": {"bins": ["curl"], "env": ["MEDIAIO_API_KEY"]}, "primaryEnv": "MEDIAIO_API_KEY"}}

Media.io AI 性别转换技能

概述

该技能调用 Media.io OpenAPI，使用模型代码 effects_image_gender_swap_female 执行图像性别转换。 该 API 为异步接口：

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

适用场景

• 用户希望使用 Media.io 将人像从男性风格转换为女性风格。
• 用户提供可被 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_gender_swap_female
• 请求体：

{
	"data": {
		"image": "https://example.com/input.jpg"
	}
}

• 必需字段：
  • data.image（字符串格式 URL）
• API 文档中规定的图像约束：
  • 格式：PNG、JPEG、JPG
  • 文件大小：0.0 MB 至 19.5 MB
  • 分辨率：300×300 至 4000×4000
  • 宽高比：1:2 至 2:1

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. 使用 data.image 字段调用 effects_image_gender_swap_female 接口。
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_gender_swap_female 
	--header 'Content-Type: application/json' 
	--header "X-API-KEY: $MEDIAIO_API_KEY" 
	--data '{
	"data": {
		"image": "https://example.com/input.jpg"
	}
}'

查询任务结果

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/