Jobs and polling
Nothing generates inside a request. A block texture takes seconds and a model can take many minutes, so every generation endpoint answers 202 Accepted straight away with a job handle, and you poll that handle.
POST /packs/my-pack/textures → 202 { "job": "my-pack:texture:mossy_bricks", … }
GET /jobs/my-pack:texture:mossy_bricks → { "status": "generating", … }
GET /jobs/my-pack:texture:mossy_bricks → { "status": "ready", "asset": { … } }
GET /packs/my-pack/assets/texture/mossy_bricks → the PNGstatus | Meaning |
|---|---|
generating | Still running. Keep polling. |
ready | Done. Fetch the file. |
error | Failed. error says why, and the credits have been refunded. |
The job response also carries the full asset, so you don't need a second
call to see what was made.
Job handles#
A handle is <pack>:<kind>:<name>, which is also the asset's id: the asset
itself is the job record. That means a handle keeps working long after the
generation finished, and the asset listing is how
you recover handles from an earlier run.
Treat the handle as an opaque string. To tell assets apart, read the asset's
type field (block, item3d, dialog and so on), not the handle.
A player Skin belongs to no pack, so its handle
is skin:<id> and its answer carries skin instead of asset.
A pack import has a different handle,
<pack>:import. Polling it returns the same three statuses, plus an import
report of what came in and what was left out.
Shaders, VFX and emotes are kept apart from a pack's files, and an
AI edit changes an asset that already exists, so
their handles name that instead of a file format: <pack>:shader:<id>,
<pack>:vfx:<id>, <pack>:emote:<id>, <pack>:emote_group:<id> and
<pack>:edit:<key>. They poll the
same way and answer the same three statuses, without an asset in the answer.
An edit's job reads ready once the change is saved. The asset listing includes shaders, VFX,
emotes and emote groups, with these handles as their ids.
Polling always ends#
A loop that waits for the status to leave generating is safe to write. A
run that dies without reporting reads as error after 25 minutes (45 for a 3D
Model), so the loop always ends.
How often to poll
Every couple of seconds is plenty for blocks, items and icons, which come back in seconds. A model takes minutes, so back off: polling spends the key's read budget, and at two seconds a job, four jobs in flight is the most it covers. See Rate limits.
A full loop#
Create a pack, generate a block, wait, download the pack:
#!/usr/bin/env bash
set -euo pipefail
API=https://api.resourcepack.ai/v1
AUTH="Authorization: Bearer $RPAI_KEY"
pack=$(curl -s -X POST "$API/packs" -H "$AUTH" -H 'Content-Type: application/json' \
-d '{"name":"Script Test"}' | jq -r .pack.slug)
job=$(curl -s -X POST "$API/packs/$pack/textures" -H "$AUTH" -H 'Content-Type: application/json' \
-d '{"prompt":"cracked obsidian with faint purple veins","mode":"vanilla","vanillaTarget":"stone","size":16}' \
| jq -r .job)
while :; do
status=$(curl -s "$API/jobs/$job" -H "$AUTH" | jq -r .status)
[ "$status" != "generating" ] && break
sleep 2
done
if [ "$status" = "error" ]; then
curl -s "$API/jobs/$job" -H "$AUTH" | jq -r .error >&2
exit 1
fi
curl -s "$API/packs/$pack/export" -H "$AUTH" -o "$pack.zip"A failed generation leaves the asset in the pack with its error, and the credits are already refunded, so always check the status you stopped on.