\r \r

Media.io AI Gender Swap Skill\r

\r

Overview\r

This skill calls Media.io OpenAPI to run image gender swap using model code effects_image_gender_swap_female.\r The API is asynchronous:\r

1. Submit generation request and get task_id.\r
2. Poll task result endpoint until the task is finished.\r \r

When To Use\r

• The user wants to transform a portrait from male to female style using Media.io.\r
• The user can provide an image URL reachable by Media.io servers.\r
• The user wants task-based generation with polling.\r \r

When Not To Use\r

• The user asks for local file upload only (this API expects image URL input).\r
• The user asks for non-Media.io providers.\r
• The user asks for real-time synchronous image output in one call.\r \r

Requirements\r

\r

Environment Variables\r

| Variable | Required | Description |\r |---|---|---|\r | MEDIAIO_API_KEY | Yes | Media.io OpenAPI key, used in header X-API-KEY. |\r \r

Base Headers\r

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

Supported Endpoints\r

\r

1) Query Credits\r

• Method: POST\r
• Endpoint: https://openapi.media.io/user/credits\r
• Body: {}\r
• Purpose: check available credits before generation.\r \r

2) Create Gender Swap Task\r

• Method: POST\r
• Endpoint: https://openapi.media.io/generation/effects/effects_image_gender_swap_female\r
• Body:\r

{\r
	"data": {\r
		"image": "https://example.com/input.jpg"\r
	}\r
}\r
```\r
- Required field:\r
	- `data.image` (string URL)\r
- Image constraints from API doc:\r
	- Format: PNG, JPEG, JPG\r
	- File size: 0.0 MB to 19.5 MB\r
	- Resolution: 300x300 to 4000x4000\r
	- Aspect ratio: 1:2 to 2:1\r
\r
### 3) Query Task Result\r
- Method: `POST`\r
- Endpoint: `https://openapi.media.io/generation/result/{task_id}`\r
- Body: `{}`\r
- Path parameter:\r
	- `task_id` (string, required)\r
\r
## Request and Response Contract\r
\r
### Common Success Envelope\r
```json\r
{\r
	"code": 0,\r
	"msg": "",\r
	"data": {},\r
	"trace_id": "..."\r
}\r
```\r
\r
### Create Task Response\r
- On success, `data.task_id` is returned.\r
\r
### Task Result Response\r
- `data.status` can be one of the following values:\r
	- `waiting`: queued\r
	- `processing`: running\r
	- `completed`: completed successfully\r
	- `failed`: failed\r
	- `timeout`: timed out\r
- `data.reason`: provides additional context (e.g., `success` or error message)\r
- When status is `completed`:\r
	- `data.result` is an array of output objects with generated image URLs\r
	- Each result object contains `val` (internal path), `preview` (public HTTPS URL), and `status` (completion status)\r
\r
## Standard Invocation Flow\r
1. Call `user/credits` to verify balance.\r
2. Call `effects_image_gender_swap_female` with `data.image`.\r
3. Extract `task_id`.\r
4. Poll `generation/result/{task_id}` every 3 to 5 seconds.\r
5. Stop when status is `completed` or `failed`.\r
6. Return output URLs from `data.result` when `completed`.\r
\r
## cURL Examples\r
\r
### Query Credits\r
```bash\r
curl --request POST \\r
	--url https://openapi.media.io/user/credits \\r
	--header 'Content-Type: application/json' \\r
	--header "X-API-KEY: $MEDIAIO_API_KEY" \\r
	--data '{}'\r
```\r
\r
### Create Gender Swap Task\r
```bash\r
curl --request POST \\r
	--url https://openapi.media.io/generation/effects/effects_image_gender_swap_female \\r
	--header 'Content-Type: application/json' \\r
	--header "X-API-KEY: $MEDIAIO_API_KEY" \\r
	--data '{\r
	"data": {\r
		"image": "https://example.com/input.jpg"\r
	}\r
}'\r
```\r
\r
### Query Task Result\r
```bash\r
curl --request POST \\r
	--url https://openapi.media.io/generation/result/\x3Ctask_id> \\r
	--header 'Content-Type: application/json' \\r
	--header "X-API-KEY: $MEDIAIO_API_KEY" \\r
	--data '{}'\r
```\r
\r
#### Successful Response Example\r
```json\r
{\r
	"code": 0,\r
	"msg": "",\r
	"data": {\r
		"task_id": "effect-86f0f82a-36dc-4a7c-928a-721a18ef482f",\r
		"status": "completed",\r
		"reason": "success",\r
		"result": [\r
			{\r
				"val": "aicloudtmp/550160908/3/202603/1/combo_tm_alg-20260317165022-802800-60eb3-dwt.png",\r
				"preview": "https://url_to_generated_image.png",\r
				"status": "completed"\r
			}\r
		]\r
	},\r
	"trace_id": "a18315ba568b5c34407808d12cbc8457"\r
}\r
```\r
\r
Response fields when status is `completed`:\r
- `data.task_id`: unique task identifier\r
- `data.status`: `completed` indicates successful completion\r
- `data.reason`: `success` indicates no error occurred\r
- `data.result`: array of output objects, each containing:\r
	- `val`: internal file path of the generated image\r
	- `preview`: publicly accessible HTTPS URL for the generated image with expiration and signature\r
	- `status`: `completed` for each result item\r
\r
## Error Handling Guidance\r
- Treat `code != 0` as failure.\r
- Typical authentication errors:\r
	- `374004`: not authenticated. Apply for an APP KEY at https://developer.media.io/.\r
- Typical request validation error:\r
	- `490000`: params error\r
- Typical billing/credits error:\r
	- `490505`: insufficient credits. Recharge before invoking generation APIs.\r
- Always include `trace_id` in logs for troubleshooting.\r
\r
## Agent Behavior Requirements\r
- Validate that input contains a non-empty image URL before calling the create endpoint.\r
- Do not claim immediate output after task creation; always poll by `task_id`.\r
- If credits are insufficient, return a clear message and stop instead of retry loops.\r
- Avoid exposing raw API keys in logs or responses.\r
\r
## Safety and Compliance Notes\r
- Only process user-provided or user-authorized images.\r
- Do not imply identity verification or biometric certainty from generated images.\r
- Generated output is synthetic media and should be presented as edited content.\r
\r
## References\r
- Media.io platform: https://developer.media.io/\r
- API documentation: https://platform.media.io/docs/