AI Hairstyle Generator

Try different hairstyles and accessories on photos using AI via Media.io OpenAPI. Preview new haircuts, hair colors, glasses, hats. AI hairstyle generator, h...

Security Scan

The skill's code-less instructions, required binary (curl), and single required credential (MEDIAIO_API_KEY) align with its stated purpose of calling Media.io's async hairstyle-generation API.

Purpose & Capability

Name/description match the declared requirements: the skill only needs a single Media.io API key and curl to call Media.io endpoints for hairstyle generation. Nothing requested (no unrelated cloud creds or system files) appears out of scope.

Instruction Scope

SKILL.md instructs only to call Media.io endpoints (credits, create task, poll results), validate an external image URL, and avoid exposing API keys in logs. It does not instruct reading unrelated files, environment variables, or config paths.

Install Mechanism

There is no install spec (instruction-only skill). No downloads or archive extraction are required, so no elevated install risk is introduced by the skill itself.

Credentials

Only MEDIAIO_API_KEY is required and is the primary credential for the stated API usage. No additional secrets or unrelated environment variables are requested.

Persistence & Privilege

The skill does not request always:true and is user-invocable only. It does not attempt to modify other skills or agent-wide settings in the provided instructions.

Assessment

This skill appears coherent, but remember: using it will send user-provided images (via their public URLs) to Media.io for processing and will consume credits on the associated API key. Before installing, verify the MEDIAIO_API_KEY has appropriate scope and billing limits, avoid sending sensitive/controlled images, ensure users consent to external processing, and rotate/store the API key securely. Also confirm your agent implementation actually avoids logging the raw X-API-KEY (SKILL.md advises this but the runtime must enforce it). If you need local-file support, note this skill only accepts URLs — do not supply local paths without first uploading to a secure URL you control.

Media.io AI Hairstyle Generator Skill

Overview

This skill calls Media.io OpenAPI to run hairstyle generation using model code effects-image-hairstyle-studio. The API is asynchronous:

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

When To Use

• The user wants hairstyle transformation from a reference portrait.
• The user can provide an image URL reachable by Media.io servers.
• The user wants task-based generation with polling.

When Not To Use

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

Requirements

Environment Variables

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

Base Headers

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

Supported Endpoints

1) Query Credits

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

2) Create Hairstyle Task

• Method: POST
• Endpoint: https://openapi.media.io/generation/effects/effects-image-hairstyle-studio
• Body:

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

• Required fields:
  • data.images (string URL)

3) Query Task Result

• Method: POST
• Endpoint: https://openapi.media.io/generation/result/{task_id}
• Body: {}
• Path parameter:
  • task_id (string, required)

Request and Response Contract

Common Success Envelope

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

Create Task Response

• On success, data.task_id is returned.

Task Result Response

• data.status can be one of the following values:
  • waiting: queued
  • processing: running
  • completed: completed successfully
  • failed: failed
  • timeout: timed out
• data.reason: provides additional context (e.g., success or error message)
• When status is completed:
  • data.result is an array of output objects with generated URLs
  • Each result object contains val (internal path), preview (public HTTPS URL), and status (completion status)

Standard Invocation Flow

1. Call user/credits to verify balance.
2. Call effects-image-hairstyle-studio with data.images.
3. Extract task_id.
4. Poll generation/result/{task_id} every 3 to 5 seconds.
5. Stop when status is completed or failed.
6. Return output URLs from data.result when completed.

cURL Examples

Query Credits

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

Create Hairstyle Task

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

Query Task Result

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

Successful Response Example

{
	"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"
}

Response fields when status is completed:

• data.task_id: unique task identifier
• data.status: completed indicates successful completion
• data.reason: success indicates no error occurred
• data.result: array of output objects, each containing:
  • val: internal file path of the generated asset
  • preview: publicly accessible HTTPS URL for the generated asset
  • status: completed for each result item

Error Handling Guidance

• Treat code != 0 as failure.
• Typical authentication errors:
  • 374004: not authenticated. Apply for an APP KEY at https://developer.media.io/.
• Typical request validation error:
  • 490000: params error
• Typical billing/credits error:
  • 490505: insufficient credits. Recharge before invoking generation APIs.
• Always include trace_id in logs for troubleshooting.

Agent Behavior Requirements

• Validate that input contains a non-empty image URL before calling the create endpoint.
• Do not claim immediate output after task creation; always poll by task_id.
• If credits are insufficient, return a clear message and stop instead of retry loops.
• Avoid exposing raw API keys in logs or responses.

Safety and Compliance Notes

• Only process user-provided or user-authorized images.
• Do not imply identity verification or biometric certainty from generated images.
• Generated output is synthetic media and should be presented as edited content.

References

• Media.io platform: https://developer.media.io/
• API documentation: https://platform.media.io/docs/