Pull your graphics into your build automatically
With an API key your game repository fetches the current versions of your graphics from your NoAliasTools account by itself, for example on every build with GitHub Actions. You change a graphic, and the next build has it.
How it works
Your graphics are files in your cloud projects. Your pipeline fetches them with an API key in your engine’s format, for Godot, Unity, Phaser, Aseprite or TexturePacker, with atlas, clips and frame durations. If nothing changed, it downloads nothing. No more exporting by hand and no outdated graphics in the repository.
API keys are part of the Studio plan. See plans
Setup
- Create a key in your account under “API keys”. Give it a name, limit it to one project if you like and set an expiry date.
- Copy the key right away. It is shown only this once.
- Store it in your pipeline as the secret NOALIAS_API_KEY. On GitHub you find this under Settings → Secrets and variables → Actions.
- In your build, download your project’s export in your engine’s format and unpack it into your game’s asset folder.
Formats
Choose your engine’s format with format=. Every ZIP also contains SpriteForge/runtime.json and SpriteForge/export-manifest.json with clips, frame durations and playback mode.
- format=godot
- Godot: SpriteFrames as .tres with atlas PNG.
- format=unity
- Unity: atlas PNG with JSON and an importer script for the editor.
- format=phaser
- Phaser: atlas PNG with JSON to load as an atlas.
- format=aseprite
- Aseprite JSON with frame tags and durations; many engines and tools read it.
- format=texturepacker-hash
- TexturePacker JSON with frames as an object.
- format=texturepacker-array
- TexturePacker JSON with frames as a list.
- format=png
- One PNG sprite sheet per clip, with no metadata besides the manifest.
- format=gif
- One animated GIF per clip, for previews for example.
More options: mode=atlas packs all clips onto shared pages, mode=batch gives one set per clip; scales=1,2 exports several sizes (1 to 4); trim, extrude, spacing, power_of_two and max_size control packing; normal_maps=1 and palette_variants=1 add normal maps and palette variants.
What you can fetch
All addresses start with https://api.noaliastools.com/api/v1/build and answer GET and HEAD.
- /projects/{project}/export?format=…
- All graphics of a project in the chosen format as a ZIP, each file in a folder of its own.
- /files/{file}/export?format=…
- One graphic in the chosen format as a ZIP; with clip= only one clip.
- /projects
- Your projects with name and last change.
- /files
- Your current files with size, checksum and download address. With ?project_id= only those of one project.
- /files/{file}/current
- The editable SpriteForge file, if you need the source.
- /assets
- Finished images from PixelFoundry and your SpriteForge files.
- /results
- Your assistant’s finished results, each with the SpriteForge file (/project) and a PNG sprite sheet of the main clip (/sheet.png).
Lists come in pages of 50 entries; page and per_page (up to 100) take you further.
Examples
Fetch all graphics of a project for Godot in two sizes; PROJECT_ID is in the list under /projects:
# Keep sprites.etag and sprites.zip between runs.
curl --fail --silent --show-error \
--header "Authorization: Bearer $NOALIAS_API_KEY" \
--etag-compare sprites.etag --etag-save sprites.etag \
--output sprites.zip \
"https://api.noaliastools.com/api/v1/build/projects/$PROJECT_ID/export?format=godot&scales=1,2"
Download only when something changed. curl keeps the ETag in sprites.etag for this; if nothing changed you get HTTP 304 without content, and your existing export stays valid.
For GitHub Actions you store NOALIAS_API_KEY as an Actions secret and the project ID as the variable NOALIAS_PROJECT_ID. This workflow fetches the graphics for Godot and unpacks them into assets/sprites:
name: Sprites
on: [push, workflow_dispatch]
permissions:
contents: read
jobs:
sprites:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download sprites
env:
NOALIAS_API_KEY: ${{ secrets.NOALIAS_API_KEY }}
PROJECT_ID: ${{ vars.NOALIAS_PROJECT_ID }}
run: |
curl --fail --silent --show-error \
--header "Authorization: Bearer $NOALIAS_API_KEY" \
--output sprites.zip \
"https://api.noaliastools.com/api/v1/build/projects/$PROJECT_ID/export?format=godot"
unzip -o sprites.zip -d assets/sprites
Limits and security
- A key can only read. It changes and deletes nothing and has no access to your assistant, shares or billing.
- It sees only your own projects, not other people’s team projects. If it is limited to one project, it sees only that one.
- There are 60 requests per minute for your account and 120 per IP address. Above that the API answers 429 and tells you in Retry-After how many seconds to wait.
- Revoking and expiry end access at once. If you change or reset your password, all keys are revoked and you create new ones.
- If your plan ends, keys read nothing more. If you book Studio again, they work again as long as they have not expired or been revoked.
- Pass the key only in the Authorization header. Never put it in addresses, files in the repository or logs, and leave out set -x and curl -v in the pipeline.
- If your workflow runs in public, do not publish the downloaded graphics as a public artifact.