# Portrait Descriptions Extractor (`dadhalfdev/portrait-descriptions-extractor`) Actor This extractor uses advanced vision AI to analyze images of people and extract incredibly detailed visual metadata in seconds. Provide image URLs or upload files directly, and the extractor will parse out up to 17 data points. You can process up to 100 images per run. - **URL**: https://apify.com/dadhalfdev/portrait-descriptions-extractor.md - **Developed by:** [Marco Rodrigues](https://apify.com/dadhalfdev) (community) - **Categories:** Integrations, Agents, Automation - **Stats:** 3 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 🖼️ Portrait Image Description Extractor Want to turn portrait photos into structured, actionable data? This extractor uses advanced vision AI to analyze images of people and extract incredibly detailed visual metadata in seconds! You can **provide image URLs or upload files directly**, and the extractor will parse out up to 17 data points, neatly packing all the physical characteristics, clothing, emotions, and environmental context into a structured JSON dataset or CSV file. You can process **up to 100 images per run**. ### 💡 Perfect for... - **Photographers & Creatives:** Automatically tag and catalog large portfolios of portrait photos with metadata. - **E-commerce & Fashion:** Extract clothing, style, and demographic data from model photos. - **Casting & Talent Agencies:** Organize headshots by specific physical traits (age range, hair style, eye color) to build searchable databases. - **Data Analysts & Researchers:** Analyze demographic representation, emotional sentiment, or fashion trends in visual media. - **🤖 AI Image Generation:** Generate structured text prompts or captions from reference images to train LoRA models or instruct Midjourney/Stable Diffusion. - **🔗 Integrations:** Perfect for enriching image databases before feeding them to search engines or other apps. - **📚 RAG Systems:** Feed detailed visual descriptions into Retrieval-Augmented Generation pipelines to allow users to semantically search for specific types of people in your image database. ### ✨ Why you'll love this extractor - 🎯 **Deep Extraction:** Pulls out specific nuances like `smile_intensity`, `skin_tone`, `expression`, and separates `lighting` from `time_of_day`. - ⚙️ **AI-Powered Accuracy:** Uses state-of-the-art vision models to understand complex visual context that traditional algorithms miss. - ⏱️ **Instant Structuring:** Turns raw pixels into a highly organized, searchable database instantly. ### 📦 What's inside the data? For every image you input, you will get: - **Demographics:** `gender`, `age_range`, `ethnicity` - **Physical Traits:** `hair_color`, `hair_style`, `eye_color`, `skin_tone` - **Style & Appearance:** `clothing`, `accessories` - **Emotion & Expression:** `expression`, `emotion`, `smile_intensity` - **Environment & Context:** `time_of_day`, `lighting`, `background_description`, `setting` - **Summary:** A concise 1-2 sentence overall visual `description`. - **Source:** The original `image_url` (or Apify Key-Value Store link if uploaded) ### 🚀 How to use The actor accepts both **direct image URLs** and **direct file uploads**. #### Option 1: Using Image URLs If you have images hosted online, you can paste the direct links (ending in .jpg, .png, etc.). * **Stock Photo Sites (Unsplash, Pexels):** Find an image, **right-click**, and select **"Copy image address"**. ![Unsplash](https://i.postimg.cc/7Z7R3yZX/Screenshot-From-2026-03-18-12-57-21.png) ![Pexels](https://i.postimg.cc/6QqYHJWX/Screenshot-From-2026-03-18-13-00-49.png) * **AI-Generated Portraits:** [Lummi.ai](https://www.lummi.ai/) is a fantastic resource. Just right-click and copy the image address! #### Option 2: Uploading Files Directly If you have images on your computer: 1. Look for the `input_images` field in the actor input. 2. Click the upload button to select files from your computer. Apify will automatically handle uploading them and passing the secure URLs to the extractor. #### Run the Extractor! 1. **Provide your images** (via URLs or file upload) in the input configuration. 2. **Click Start** and let the vision AI do its magic! ✨ 3. Once it's done, you can export your structured data as a CSV, Excel spreadsheet, or JSON file. --- #### Tech details for developers 🧑‍💻 **Input Example:** ```json { "input_images": [ "https://images.unsplash.com/photo-1534528741775-53994a69daeb?auto=format&fit=crop&q=80&w=1000", "https://api.apify.com/v2/key-value-stores/YOUR_STORE_ID/records/uploaded-image.jpg" ] } ```` **Output Example:** ```json { "image_url": "https://images.unsplash.com/photo-1534528741775-53994a69daeb?auto=format&fit=crop&q=80&w=1000", "gender": "Female", "age_range": "20-30", "hair_color": "Brown", "hair_style": "Long, straight, parted in the middle", "eye_color": "Brown", "skin_tone": "Fair", "ethnicity": "Caucasian", "clothing": "A dark, possibly black or navy, top or dress with a high neckline.", "accessories": null, "expression": "Serious, composed, looking directly at the camera", "emotion": "Thoughtful, confident", "smile_intensity": "None", "time_of_day": "Indoor/Studio", "lighting": "Soft studio lighting, evenly illuminating the face with subtle shadows to create depth.", "background_description": "A plain, solid, light grey or off-white backdrop.", "setting": "Studio", "description": "A studio portrait of a young woman with long brown hair, looking directly at the camera with a serious and composed expression." } ``` **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `input_images` | array of strings | Yes | List of direct image URLs or uploaded image files to extract portrait data from. | # Actor input Schema ## `input_images` (type: `array`): Provide a list of direct image URLs to analyze, or use the file uploader to upload images from your device. ## Actor input object example ```json { "input_images": [ "https://images.unsplash.com/photo-1606122017369-d782bbb78f32?w=600&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8cG9ydHJhaXRzfGVufDB8fDB8fHww", "https://images.unsplash.com/photo-1530785602389-07594beb8b73?q=80&w=687&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" ] } ``` # Actor output Schema ## `overview` (type: `string`): Table view using the dataset 'portrait\_description' view. ## `results` (type: `string`): All items from the default dataset without view transformation. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "input_images": [ "https://images.unsplash.com/photo-1606122017369-d782bbb78f32?w=600&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8cG9ydHJhaXRzfGVufDB8fDB8fHww", "https://images.unsplash.com/photo-1530785602389-07594beb8b73?q=80&w=687&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" ] }; // Run the Actor and wait for it to finish const run = await client.actor("dadhalfdev/portrait-descriptions-extractor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "input_images": [ "https://images.unsplash.com/photo-1606122017369-d782bbb78f32?w=600&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8cG9ydHJhaXRzfGVufDB8fDB8fHww", "https://images.unsplash.com/photo-1530785602389-07594beb8b73?q=80&w=687&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D", ] } # Run the Actor and wait for it to finish run = client.actor("dadhalfdev/portrait-descriptions-extractor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "input_images": [ "https://images.unsplash.com/photo-1606122017369-d782bbb78f32?w=600&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8cG9ydHJhaXRzfGVufDB8fDB8fHww", "https://images.unsplash.com/photo-1530785602389-07594beb8b73?q=80&w=687&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" ] }' | apify call dadhalfdev/portrait-descriptions-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=dadhalfdev/portrait-descriptions-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Portrait Descriptions Extractor", "description": "This extractor uses advanced vision AI to analyze images of people and extract incredibly detailed visual metadata in seconds. Provide image URLs or upload files directly, and the extractor will parse out up to 17 data points. You can process up to 100 images per run.", "version": "0.1", "x-build-id": "MdP8n3LM7dc4l5n8A" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dadhalfdev~portrait-descriptions-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dadhalfdev-portrait-descriptions-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/dadhalfdev~portrait-descriptions-extractor/runs": { "post": { "operationId": "runs-sync-dadhalfdev-portrait-descriptions-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/dadhalfdev~portrait-descriptions-extractor/run-sync": { "post": { "operationId": "run-sync-dadhalfdev-portrait-descriptions-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "input_images" ], "properties": { "input_images": { "title": "List of Portraits (Photos or Images)", "minItems": 1, "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Provide a list of direct image URLs to analyze, or use the file uploader to upload images from your device." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```