Endpoints

GET — Job Status

Poll the status and retrieve the result of an image generation job. Call this every 2 seconds until status is "complete" or "failed".

Overview

GEThttps://api.sharkapi.dev/v1/jobs/:id

Replace :id with the job_id returned from POST /v1/generate.

ℹ

Wallet deductions only occur when this endpoint returns status: "complete" with a valid image_url. Failed or moderated jobs are never charged.

Request

Parameter	Type	Required	Description
Authorization	string	Required	Bearer token. Format: "Bearer sk_live_..."
:id	string	Required	Job ID from the generation response (e.g. job_8f2a9d3c).

Response

HTTP 200 OK regardless of job status (successful poll, not successful generation).

Parameter	Type	Required	Description
job_id	string	Required	Unique job identifier.
status	string	Required	Current status: "queued" \| "processing" \| "complete" \| "failed" \| "moderated".
image_url	string \| null	Required	S3 URL of the generated image. Present only when status is "complete".
mode	string	Required	"1k" or "2k".
prompt	string	Required	The prompt used for this job.
cost	string \| null	Required	Final cost (e.g. "$0.02"). Set only after status "complete". Null otherwise.
error	string \| null	Required	Error message if status is "failed". Null otherwise.
created_at	string	Required	ISO 8601 timestamp of job creation.
completed_at	string \| null	Required	ISO 8601 timestamp of job completion. Null if not yet complete.

Completed job

json

{
  "job_id":       "job_8f2a9d3c",
  "status":       "complete",
  "image_url":    "https://cdn.sharkapi.dev/out/job_8f2a9d3c.jpg",
  "mode":         "2k",
  "prompt":       "A great white shark in bioluminescent waters",
  "cost":         "$0.02",
  "error":        null,
  "created_at":   "2024-01-15T10:23:44Z",
  "completed_at": "2024-01-15T10:23:59Z"
}

Failed job

json

{
  "job_id":    "job_xyz789",
  "status":    "failed",
  "image_url": null,
  "cost":      null,
  "error":     "Generation service timeout. No charge applied.",
  "created_at":"2024-01-15T10:30:00Z",
  "completed_at": null
}

Job statuses

queued

Job received, waiting to be picked up by the generation worker.

processing

Generation actively in progress.

complete

Done. image_url is set. Wallet has been charged.

failed

Generation failed (timeout, server error). No charge applied.

moderated

Prompt or image was blocked by content moderation. No charge applied.

Polling pattern

Poll every 2 seconds. Handle all terminal states (complete, failed, moderated).

JavaScript / Node.js

javascript

async function waitForJob(jobId, token) {
  const url     = `https://api.sharkapi.dev/v1/jobs/${jobId}`;
  const headers = { "Authorization": `Bearer ${token}` };

  while (true) {
    const res = await fetch(url, { headers });
    const job = await res.json();

    switch (job.status) {
      case "complete":
        return job; // ← image_url is ready
      case "failed":
        throw new Error(job.error ?? "Job failed");
      case "moderated":
        throw new Error("Request blocked by content moderation");
      default:
        // queued or processing — keep polling
        await new Promise(r => setTimeout(r, 2000));
    }
  }
}

// Usage
const job = await waitForJob("job_8f2a9d3c", process.env.SHARKAPI_TOKEN);
console.log(job.image_url); // "https://cdn.sharkapi.dev/..."

Python

python

import time, httpx

def wait_for_job(job_id: str, token: str) -> dict:
    url     = f"https://api.sharkapi.dev/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {token}"}

    while True:
        job = httpx.get(url, headers=headers).json()

        match job["status"]:
            case "complete":
                return job
            case "failed":
                raise RuntimeError(job.get("error", "Job failed"))
            case "moderated":
                raise RuntimeError("Blocked by content moderation")
            case _:
                time.sleep(2)

Errors

Parameter	Type	Required	Description
404 Not Found	HTTP	Optional	Job ID does not exist or does not belong to your account.
401 Unauthorized	HTTP	Optional	Missing or invalid token.