What can a pattern contain?

{n} for the position starting at one, {name} for the original name without its extension, and {date} for today in ISO form. The extension is kept automatically.

Does it rename my files?

No, and that is deliberate. It returns the mapping so your own code, which has the files, does the move. Nothing is uploaded except the names.

What is the collisions field?

Names that two or more files would share, which happens with a pattern that has no {n}. Renaming into a collision destroys a file, so it is reported instead of being handed back silently.

Batch rename API

Map a list of filenames through a pattern. {n}, {name} and {date} are substituted.

Get a free token Full API reference

Endpoint	POST https://astralbatch.com/api/v1/batch-rename
Auth	Bearer token, free
Sends	inputs: text[]
Returns	result: json
Price	Free. 1,000 calls a day, 60 a minute.

When to call it

Renaming is the step that decides whether an archive can be found again in a year. Working out the new names as data, before anything is moved, means you can see what the result will be and catch the pattern that maps two files to the same name.

For a one-off, the browser version needs no token and never sends your data anywhere: it runs on your own machine.

Example

curl

curl -X POST https://astralbatch.com/api/v1/batch-rename \
  -H "Authorization: Bearer ast_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["IMG_4821.jpg","IMG_4822.jpg","scan.png"], "option": "paris-2026-{n}"}'

response

{
  "tool": "batch-rename",
  "result": "{\n  \"pattern\": \"paris-2026-{n}\",\n  \"collisions\": [],\n  \"files\": [\n    {\n      \"from\": \"IMG_4821.jpg\",\n      \"to\": \"paris-2026-1.jpg\"\n    },\n    {\n      \"from\": \"IMG_4822.jpg\",\n      \"to\": \"paris-2026-2.jpg\"\n    },\n    {\n      \"from\": \"scan.png\",\n      \"to\": \"paris-2026-3.png\"\n    }\n  ]\n}",
  "chars": 288,
  "ms": 1
}

In your language

JavaScript

const res = await fetch("https://astralbatch.com/api/v1/batch-rename", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASTRAL_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"inputs": ["IMG_4821.jpg","IMG_4822.jpg","scan.png"], "option": "paris-2026-{n}"}),
});
if (!res.ok) throw new Error((await res.json()).detail);
const { result } = await res.json();

Python

import os, requests

res = requests.post(
    "https://astralbatch.com/api/v1/batch-rename",
    headers={"Authorization": f"Bearer {os.environ['ASTRAL_TOKEN']}"},
    json={"inputs": ["IMG_4821.jpg","IMG_4822.jpg","scan.png"], "option": "paris-2026-{n}"},
    timeout=30,
)
res.raise_for_status()
result = res.json()["result"]

Parameters

Field	Type	Notes
inputs	string[]	Required. Between 2 and 20 items. Up to 10,000,000 characters per call.
option	string	See the example above.

Errors

Errors are RFC 7807 problem documents with a stable type you can branch on.

missing-token	401	No Authorization header.
bad-request	400	inputs missing or the wrong type.
tool-failed	422	The input could not be processed. detail says why.
quota-exceeded	429	Past 1,000 calls today.

Questions

What can a pattern contain?: {n} for the position starting at one, {name} for the original name without its extension, and {date} for today in ISO form. The extension is kept automatically.
Does it rename my files?: No, and that is deliberate. It returns the mapping so your own code, which has the files, does the move. Nothing is uploaded except the names.
What is the collisions field?: Names that two or more files would share, which happens with a pattern that has no {n}. Renaming into a collision destroys a file, so it is reported instead of being handed back silently.

Other endpoints

A token takes thirty seconds

Free, no card, 1,000 calls a day, and the same token works on astraltext.com, astralpdf.com, astraljson.com and astralbatch.com.

Get a free token