# KURA (`tropical_lease/kura`) Actor
KURA: Context-aware Ads Agent Actor – Turn Any User Mood into Creatives
Generate product recommendations and ready-to-use ad creatives from a simple mood/scenario prompt.
- **URL**: https://apify.com/tropical\_lease/kura.md
- **Developed by:** [kura](https://apify.com/tropical_lease) (community)
- **Categories:** AI, Agents, E-commerce
- **Stats:** 4 total users, 1 monthly users, 93.1% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
Pay per usage
This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage
## 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
## 🏯 KURA: Context-aware Ads Agent
**Turn Any User Mood into Shoppable Creatives.**
> *"Kura (倉 / 蔵) means 'storehouse' in Japanese — a quiet repository where valuable things are kept."*
Kura works invisibly in the background, acting as a storehouse of contextual logic. It organizes user scenarios, matches them with products, and generates high-quality ad creatives automatically.
---
### 🌟 The Mission: Context-Aware Ads
Every year, countless brilliant products fail—not because they're bad, but because their ads never reach the right people. Small companies burn budget on broad targeting; customers are overwhelmed by generic noise.
**Kura was built to change that.**
* **For Consumers:** Ads become enjoyable, serendipitous discoveries.
* **For Startups:** Customer acquisition becomes efficient and predictable.
We believe discovery shouldn't be a privilege. It should be a system anyone can access.
---
### 🎮 Live Produdct Demo: See Kura in Action
We built and hosted a **Mock Search Engine** to visualize the potential of this Actor.
Imagine a user searching normally, but seamlessly discovering highly relevant Kura-generated ads mixed into the results.
#### 👉 [Try the Live Visualizer (apify-hack.vercel.app)](https://apify-hack.vercel.app/)
*(Type anything like "south Californian style patio" or "home office" to see the ads appear)*
| Landing Page | Ads Result |
| :---: | :---: |
| 
| 
|
---
### 🧭 What This Actor Does
Kura is an API-first creative engine that runs inside Apify. It transforms a simple text prompt (a mood, scenario, or vibe) into a fully structured, ready-to-run ad campaign.
#### It supports two powerful workflows:
#### 1. 🔍 Context → Discovery (Platform Mode)
* **Input:** A mood/scenario (e.g., *"User searching for random ideas"*).
* **Process:** Kura uses **GPT-4o** to brainstorm relevant products, searches **Amazon** to find the best matches, and uses **Fal.ai** to render them into the scene.
* **Output:** A list of curated products + highly relevant lifestyle ad images.
#### 2. 🎨 Products → Creative Gen (Brand Mode)
* **Input:** A mood/scenario + **Your specific Amazon Product URLs**.
* **Process:** Kura skips the brainstorming, scrapes your exact product (extracting high-res images), and places *your* product into the new scenario.
* **Output:** Multiple variations of your product in the target context.
### What This Actor Is For
1. Large Commerce & Retail Platforms
2. Adtech startup & Marketing Agency
3. Small, Mid-size & Independent E-commerce
4. Creator Commerce
---
### 🛠️ Technology Stack
This Actor is a "Glue Code" masterpiece, orchestrating top-tier AI models:
1. **Brain:** **OpenAI GPT-4o** (for semantic understanding and product recommendation).
2. **Eyes:** **Amazon Search Scraper** (for retrieving real-time product metadata and high-res white-background images).
3. **Hands:** **Fal.ai (Nano Banana/Gemini)** (for instruction-based image editing and seamless background synthesis).
4. **Body:** **Apify Actor** (for serverless execution and parallel processing).
---
### 📥 Input Parameters
Kura automatically detects your intent based on the input.
| Field | Type | Description |
| :--- | :--- | :--- |
| **Scenario / Mood** | `String` | **(Required)** Describe the context, vibe, or user mood.
_Example: "Some living room decor idea." or "Cozy winter gaming night"._ |
| **Amazon Product URLs** | `Array` | **(Optional)**
• **Leave empty** to let AI discover products for you.
• **Paste links** to generate creatives for specific items. |
---
### 📤 Output Structure
The Actor outputs a clean JSON dataset ready for your frontend or ad manager.
```json
{
"scenario_input": "A cozy Christmas living room",
"mode_used": "GENERATED_IDEAS",
"timestamp": "2025-12-06T20:10:00.000Z",
"recommendations": [
{
"keyword_or_title": "Red Knitted Throw Blanket",
"status": "success",
"amazon": {
"title": "Bourina Textured Throw Blanket...",
"price": "$18.99",
"url": "https://www.amazon.com/dp/B01N2Y6L...",
"image": "https://m.media-amazon.com/images/I/81xQ-k-y-xL._AC_SL1500_.jpg"
},
"generated_image": "https://fal.media/files/monkey/generated-result.png"
}
]
}
# Actor input Schema
## `scenario` (type: `string`):
Describe the scenario, the vibe, the user need (e.g., Cozy Christmas living room'). We will match suitable products and generate themed-photos
## `productUrls` (type: `array`):
If you paste links here, AI will skip keyword-mapping, product suggestion and use these specific items. Leave empty to let AI suggest products.
## `userBackgroundUrl` (type: `string`):
Paste a link to your room or backyard photo. If provided, AI will try to place the product here.
## Actor input object example
```json
{
"scenario": "I want some south californian back yard ideas.",
"productUrls": []
}
````
# Actor output Schema
## `overview` (type: `string`):
No description
# 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 = {
"scenario": "I want some south californian back yard ideas.",
"productUrls": [],
"userBackgroundUrl": ""
};
// Run the Actor and wait for it to finish
const run = await client.actor("tropical_lease/kura").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 = {
"scenario": "I want some south californian back yard ideas.",
"productUrls": [],
"userBackgroundUrl": "",
}
# Run the Actor and wait for it to finish
run = client.actor("tropical_lease/kura").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 '{
"scenario": "I want some south californian back yard ideas.",
"productUrls": [],
"userBackgroundUrl": ""
}' |
apify call tropical_lease/kura --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=tropical_lease/kura",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "KURA",
"description": "KURA: Context-aware Ads Agent Actor – Turn Any User Mood into Creatives\nGenerate product recommendations and ready-to-use ad creatives from a simple mood/scenario prompt.",
"version": "0.0",
"x-build-id": "NIr81hMSehcQCiDN9"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/tropical_lease~kura/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-tropical_lease-kura",
"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/tropical_lease~kura/runs": {
"post": {
"operationId": "runs-sync-tropical_lease-kura",
"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/tropical_lease~kura/run-sync": {
"post": {
"operationId": "run-sync-tropical_lease-kura",
"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": [
"scenario"
],
"properties": {
"scenario": {
"title": "Scenario / Mood",
"type": "string",
"description": "Describe the scenario, the vibe, the user need (e.g., Cozy Christmas living room'). We will match suitable products and generate themed-photos"
},
"productUrls": {
"title": "Specific Amazon Product URLs (Optional, only if you want to test out specific product)",
"type": "array",
"description": "If you paste links here, AI will skip keyword-mapping, product suggestion and use these specific items. Leave empty to let AI suggest products.",
"items": {
"type": "string"
}
},
"userBackgroundUrl": {
"title": "Custom Background Image URL (Optional)",
"type": "string",
"description": "Paste a link to your room or backyard photo. If provided, AI will try to place the product here."
}
}
},
"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
}
}
}
}
}
}
}
}
}
}
```