Jobs API

Animation and pose generation are asynchronous. When you start a generation, you receive a jobId that you can poll until the job completes.

Job Lifecycle

Jobs move through these statuses:

queued → running → succeeded
                 → failed

Get Job Status

GET /api/v1/jobs/:jobId

Get detailed status for a specific job, including progress information and result IDs on completion.

There are two job types with different response shapes:

• Animation jobs — returned when generating spritesheets, isometric packs (job IDs starting with rose_) or regenerating
• Pose jobs (job IDs starting with cf_) — returned when generating poses

Example

curl https://www.autosprite.io/api/v1/jobs/job_001 \
  -H "x-api-key: vspk_your_key_here"

Animation Job Response (Running)

{
  "jobId": "job_001",
  "characterId": "char_abc123",
  "videoId": "vid_001",
  "status": "running",
  "progress": { "total": 3, "completed": 1 },
  "steps": [
    { "id": "first-frame", "label": "Walk Seed Frame", "status": "succeeded" },
    { "id": "video-run", "label": "Video", "status": "running" },
    { "id": "sheet-run", "label": "Spritesheet", "status": "queued" }
  ],
  "spritesheetIds": []
}

The progress object reports how many of the job's internal steps have finished — compute a percentage with completed / total. Animation jobs typically have 3 steps (seed frame, video, spritesheet extraction).

Animation Job Response (Succeeded)

{
  "jobId": "job_001",
  "characterId": "char_abc123",
  "videoId": "vid_001",
  "status": "succeeded",
  "steps": [
    {
      "id": "video-run",
      "label": "Video",
      "status": "succeeded",
      "outputs": { "url": "https://..." }
    },
    {
      "id": "sheet-run",
      "label": "Spritesheet",
      "status": "succeeded",
      "outputs": { "sheet_url": "https://..." }
    }
  ],
  "spritesheetIds": ["ss_001"]
}

When a job succeeds, use the spritesheetIds to fetch the completed spritesheets via the Spritesheets API.

Animation Job Response (Failed)

{
  "jobId": "job_001",
  "characterId": "char_abc123",
  "videoId": "vid_001",
  "status": "failed",
  "error": "Video generation timed out",
  "steps": [],
  "spritesheetIds": []
}

Isometric Pack Job Response (Succeeded)

A succeeded isometric pack lists all eight spritesheets — one per direction — plus a zipUrl that downloads every direction at once. The zip link expires after 5 minutes; poll again for a fresh one.

{
  "jobId": "rose_3f9a1c…",
  "characterId": "char_abc123",
  "status": "succeeded",
  "steps": [
    { "id": "video-run", "label": "walk · 8 directions", "status": "succeeded" },
    { "id": "pack-sheets", "label": "walk · 8 directions", "status": "succeeded" }
  ],
  "spritesheetIds": ["ss_101", "ss_102", "ss_103", "ss_104", "ss_105", "ss_106", "ss_107", "ss_108"],
  "zipUrl": "https://... (presigned zip download)"
}

Pose Job Response (Succeeded)

Pose jobs (IDs starting with cf_) have a different response shape:

{
  "jobId": "cf_abc123",
  "status": "succeeded",
  "frameType": "pose",
  "resultUrl": "https://... (presigned URL)",
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:31:00Z"
}

List Jobs

GET /api/v1/jobs

List your recent jobs with optional filtering. Uses cursor-based pagination.

Query Parameters

Example

# List all running jobs
curl "https://www.autosprite.io/api/v1/jobs?status=running" \
  -H "x-api-key: vspk_your_key_here"

# List jobs for a specific character
curl "https://www.autosprite.io/api/v1/jobs?characterId=char_abc123&limit=5" \
  -H "x-api-key: vspk_your_key_here"

Response

{
  "jobs": [
    {
      "jobId": "job_001",
      "characterId": "char_abc123",
      "status": "succeeded",
      "error": null,
      "createdAt": "2025-01-15T10:30:00Z",
      "completedAt": "2025-01-15T10:32:00Z"
    },
    {
      "jobId": "job_002",
      "characterId": "char_abc123",
      "status": "running",
      "error": null,
      "createdAt": "2025-01-15T10:31:00Z",
      "completedAt": null
    }
  ],
  "nextCursor": "job_003",
  "hasMore": true
}

Polling Best Practices

Recommended Polling Pattern

async function waitForJob(jobId, apiKey) {
  const headers = { "x-api-key": apiKey };

  // Wait 10 seconds before first poll
  await new Promise(r => setTimeout(r, 10000));

  while (true) {
    const res = await fetch(
      `https://www.autosprite.io/api/v1/jobs/${jobId}`,
      { headers }
    );
    const job = await res.json();

    if (job.status === "succeeded") {
      return job;
    }
    if (job.status === "failed") {
      throw new Error(job.error || "Job failed");
    }

    // Poll every 5 seconds
    await new Promise(r => setTimeout(r, 5000));
  }
}

Batch Polling

When generating multiple animations, poll all jobs in parallel rather than sequentially:

async function waitForAllJobs(jobIds, apiKey) {
  return Promise.all(
    jobIds.map(id => waitForJob(id, apiKey))
  );
}

// Usage after generating animations
const { workflows } = await generateAnimations(characterId, animations);
const completedJobs = await waitForAllJobs(
  workflows.map(w => w.jobId),
  apiKey
);