resourcepack.ai
DOCS

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 PNG
statusMeaning
generatingStill running. Keep polling.
readyDone. Fetch the file.
errorFailed. 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.