Dataset to XLSX with Images

Turn a small product catalog, listing export, or research shortlist into an XLSX workbook you can actually browse visually. Paste JSON records or CSV, choose the image URL field, and download an .xlsx with real embedded thumbnails beside your data.

Compatible with Microsoft Excel through the standard XLSX file format. This is an independent tool and is not affiliated with or endorsed by Microsoft. Native Microsoft Excel rendering, sorting, and filtering have not yet been verified for this beta; see the compatibility notes below.

Free beta: there is no Actor fee. Apify platform usage, including compute, storage, and data transfer, may still consume credits or incur charges under your plan. This project does not make a run cost-free.

Open animated demo · The preview on this page is static; the link opens the looping GIF.

Illustrative layout using real workbook values and images. Up to 200 rows; public HTTPS image URLs.

What you get

• One Excel workbook containing every accepted input row, even when an image is missing or fails.
• PNG thumbnails embedded in the workbook. Images do not depend on a live IMAGE() formula or an external image fetch when the workbook opens.
• All source data cell values written as literal text, including values beginning with =, +, -, or @.
• A detailed image report and simple run totals for automation.

For your own data, this beta accepts inline data only. It does not read Apify dataset IDs, download CSV files, connect to databases, or accept API tokens. If your data came from another Actor, pass the selected records into this Actor's records input. A separate demo mode uses fictional bundled data.

Quick start

Try the fictional demo

The Console input form initially checks Try the fictional product demo. Leave the source fields absent and run it to create a clearly labeled fictional 12-product catalog with 10 bundled product images, one missing-image notice, and one rejected-image notice. It makes no requests to image hosts. Apify platform usage can still apply.

For API or CLI use, explicitly provide:

{ "demoMode": true }

Only demoMode and an optional title are accepted in demo mode. Do not include records, csvText, imageColumn, or columns, even as empty fields. An empty input object does not select the demo: demoMode defaults to false outside the prefilled Console form.

Export your own data

1. Turn demo mode off, or omit demoMode in an API input.
2. Provide either records or csvText. Omit the other field entirely.
3. Set imageColumn to the exact source field containing image URLs.
4. Optionally choose the order of data columns and a workbook title.
5. Run the Actor. In the run's Output selector, choose Download files (Excel and report), then download OUTPUT.xlsx. If that view is unavailable, open Storage → Key-value store and download OUTPUT.xlsx there.
6. Check the image report before sharing the workbook. A successful run can still have rejected, missing, failed, or skipped images.

JSON example

The image URL below is a placeholder. Replace it with a direct, public HTTPS PNG, JPEG, or WEBP URL you are permitted to download.

{
  "records": [
    {
      "sku": "00123",
      "name": "Red mug",
      "price": "12.50",
      "imageUrl": "https://example.com/images/red-mug.png"
    },
    {
      "sku": "00124",
      "name": "Item with no image",
      "price": "9.00",
      "imageUrl": ""
    }
  ],
  "imageColumn": "imageUrl",
  "columns": ["sku", "name", "price", "imageUrl"],
  "title": "Catalog preview"
}

CSV example

CSV is passed as a JSON string, with newline characters escaped. Use comma-separated CSV with a header row. Keep the records field absent.

{
  "csvText": "sku,name,imageUrl\n00123,Red mug,https://example.com/images/red-mug.png\n00124,Item with no image,\n",
  "imageColumn": "imageUrl"
}

Inputs

Field	Required	Meaning
demoMode	No	Explicit true runs the fictional bundled demo. Defaults to false; the Console form prefills true.
records	One source in real-data mode	List of 1–200 JSON objects. Omit in demo mode.
csvText	One source in real-data mode	Inline comma-separated CSV with headers and 1–200 data rows. Omit in demo mode.
imageColumn	In real-data mode	Exact, case-sensitive existing field name used to find each image URL. Omit in demo mode.
columns	No	Ordered list of 1–30 distinct source field names to export. If omitted, columns are derived in first-seen order. Omit in demo mode.
title	No	Non-blank workbook title, 1–100 characters. Defaults to Dataset to Excel with Images.

The Actor enforces conditional demo/real-data requirements, source exclusivity, and the total input and column limits at runtime. Unknown top-level input fields are rejected. Field names must be non-blank and no longer than 128 characters. CSV headers must be unique, and each record must have the same field count as the header; empty physical lines are ignored. Selecting a subset of columns does not raise the 30-column source limit.

Data fidelity

Data values are deliberately text, so Excel will not automatically turn identifiers into numbers, dates, formulas, or active URL cells. CSV leading zeros are retained. JSON integers are preserved as received by the Python runtime, including integers larger than Excel's numeric precision.

Missing fields and JSON null become empty cells. Booleans become true or false; nested arrays and objects become compact JSON text. Cells longer than 32,767 characters, non-finite numbers, and unsupported XML control or Unicode characters are rejected rather than silently truncated or altered.

Use JSON strings for identifiers and exact decimal formatting. A browser, upstream JavaScript integration, or other producer may round a large JSON number before it reaches this Actor; the Actor cannot restore digits already lost. Numbers do not retain their original JSON spelling, so use "12.50" rather than 12.50 when the trailing zero matters. Numeric calculations in Excel require an explicit conversion after export.

Files and results

The run's default key-value store contains:

Key	Content
OUTPUT.xlsx	Binary Excel workbook, MIME type application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.
SUMMARY.json	JSON report with totals and per-row image outcomes.
OUTPUT	JSON output metadata.

The default dataset contains one summary record, not the original rows. Exporting that dataset to Excel will produce only the summary; download OUTPUT.xlsx for the embedded-image workbook.

{
  "version": "0.1.0",
  "demo": false,
  "rowCount": 5,
  "columnCount": 3,
  "embeddedCount": 1,
  "missingCount": 1,
  "rejectedCount": 1,
  "failedCount": 1,
  "skippedCount": 1,
  "workbookKey": "OUTPUT.xlsx",
  "summaryKey": "SUMMARY.json"
}

Each row has one image outcome:

• embedded: a thumbnail was added.
• missing: the source image field is missing or empty.
• rejected: the source or image violates a validation or safety limit.
• failed: the image could not be downloaded or processed.
• skipped: the shared image budget or fetch deadline prevented processing.

Image errors do not remove the row. Invalid input, such as conflicting sources or too many rows, fails the run instead of silently truncating the data.

The workbook has a Dataset sheet with a thumbnail, your chosen data columns, Image status, and Image detail. The detailed JSON report's rows array uses a one-based sourceRow index into the data records, excluding the CSV header. Report rows contain safe status/detail codes rather than source URLs. The demo flag identifies fictional demo output; demo counts are 12 rows, 10 embedded, one missing, one rejected, and no failed or skipped images.

Beta limits

Limit	Value
Data rows	1–200
Source data columns	30 maximum
Total JSON input	2 MiB maximum
Downloaded image	2 MiB maximum per image
Total image download budget	20 MiB per run
Decoded image	At most 8,000,000 pixels and 4,096 pixels on either side
Concurrent image workers	4
Image-fetch phase	35 seconds
Image formats	Static PNG, JPEG, WEBP; animated images are rejected
Image transport	Direct public HTTPS URLs on port 443, at most 4,096 characters, without fragments

One MiB means 1,048,576 bytes. The image limits are safeguards, not a guarantee that every permitted image will load. Slow, protected, expired, malformed, or unavailable sources may fail. Image servers must return a matching image/png, image/jpeg, or image/webp content type. Remaining images can be skipped when the shared budget or time cap is reached. The 35-second cap applies to fetching, not the complete Actor run, which also needs startup, workbook creation, and storage time.

Image safety and privacy

• Use only data and image URLs you are allowed to share with Apify and download from their hosts.
• Download requests reveal the requester's IP address and the complete requested URL to the image host. On Apify, this is the Actor's outbound address.
• Do not submit passwords, access tokens, private files, sensitive personal data, or secret image URLs. Query strings, including signed URL tokens, are still disclosed to the host and can remain in the input or exported source data.
• URL usernames/passwords, redirects, private or other non-public IP destinations are forbidden. Authentication, custom request headers, and cookies are not supported.
• This is an export tool, not a privacy scrubber. The workbook can contain your original fields and image URLs. Review it before sharing.

Spreadsheet compatibility

Excel desktop is recommended. Thumbnails are embedded drawing objects anchored to rows, not native in-cell images. Sorting or rearranging rows is not guaranteed to keep image anchors aligned; verify the result after editing. Google Sheets imports, Excel web, and other spreadsheet applications may display or move images differently.

The beta is best for small, reviewable exports. It is not a full-fidelity backup of the source JSON, a streaming export, or a promise that protected image hosts can be accessed.

Development

Runtime: Python 3.12. The Docker entry point is python -m src. Direct runtime dependencies are pinned in requirements.txt: Apify SDK 4.0.2, XlsxWriter 3.2.9, and Pillow 12.3.0.

Install dependencies in a virtual environment with python -m pip install -r requirements.txt. To run directly without an Apify account, save a UTF-8 JSON input file and run:

python -m src --local INPUT.json local-output

Or run the bundled fictional demo without image-host requests:

python -m src --local demo/try-demo.json demo-output

The local CLI writes OUTPUT.xlsx and SUMMARY.json to the chosen directory and prints the run summary. Real-data mode makes outbound requests for valid image URLs. The Apify runtime additionally writes OUTPUT metadata and a summary dataset record.

For the Apify local workflow, save your input in storage/key_value_stores/default/INPUT.json and use apify run from this project directory. Install requirements-qa.txt for development, then run the offline tests with python -m unittest discover -s tests -v. python -m tools.make_demo regenerates the original fictional illustrations and sample workbook; python -m tools.render_preview renders file-derived previews. The previews are not screenshots from Microsoft Excel. Keep test inputs free of secrets. Do not publish or run a cloud build without first reviewing platform usage and settings.

Recommended beta run settings: 512 MiB memory and a 60-second timeout. Image processing stops at its own 35-second deadline; run startup and output storage need additional time. See QA_REVIEW.md for verification and the remaining platform checks.

Metadata follows Apify's current Actor schema conventions. The input schema deliberately has no top-level oneOf, which the Apify input meta-schema does not allow; runtime validation enforces demo exclusivity or exactly one real-data source plus imageColumn. demoMode combines prefill: true with default: false, so an API call that omits it never silently switches to fictional data.

Reference sources

• Actor definition
• Input schema specification
• Output schema specification
• Dataset schema specification
• Official schema source
• Python Docker images
• Apify SDK 4.0.2 and Actor API
• XlsxWriter 3.2.9 and Pillow 12.3.0

Schema and dependency references were checked on 2026-10-08. The beta's contract and tests, rather than later upstream releases, govern this version.