SharkAPI Documentation

https://www.sharkapi.dev

X-API-Key: sk_live_your_token_here

# Step 1 — submit a job
curl -X POST https://www.sharkapi.dev/api/v1/image \
  -H "X-API-Key: sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A great white shark in bioluminescent deep ocean, cinematic, 8K"}'

# → 202 Accepted
# { "job_id": "3a8f2c1d-...", "status": "queued", "poll_url": "/api/v1/jobs/3a8f2c1d-..." }

# Step 2 — poll every 2 seconds until completed
curl https://www.sharkapi.dev/api/v1/jobs/3a8f2c1d-... \
  -H "X-API-Key: sk_live_••••••••"

# → { "status": "completed", "image_url": "https://...supabase.co/.../generated-images/..." }

{
  "job_id":     "3a8f2c1d-7b4e-4f9a-b2d6-1c5e8f3a9b7d",
  "status":     "queued",
  "poll_url":   "/api/v1/jobs/3a8f2c1d-7b4e-4f9a-b2d6-1c5e8f3a9b7d",
  "price_usd":  0.03,
  "created_at": "2025-01-15T10:23:44Z"
}

curl -X POST https://www.sharkapi.dev/api/v1/image \
  -H "X-API-Key: sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A great white shark in bioluminescent deep ocean, cinematic, 8K",
    "variant": "1k"
  }'

# Encode your file to base64 first
IMAGE_B64=$(base64 -w 0 ./reference.jpg)   # Linux
# IMAGE_B64=$(base64 -i ./reference.jpg)   # macOS

curl -X POST https://www.sharkapi.dev/api/v1/image \
  -H "X-API-Key: sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"Transform this into a watercolor painting\",
    \"image\": \"$IMAGE_B64\"
  }"

curl -X POST https://www.sharkapi.dev/api/v1/image \
  -H "X-API-Key: sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transform this into a watercolor painting",
    "image_url": "https://your-cdn.com/photo.jpg"
  }'

curl https://www.sharkapi.dev/api/v1/jobs/3a8f2c1d-7b4e-4f9a-b2d6-1c5e8f3a9b7d \
  -H "X-API-Key: sk_live_••••••••"

{
  "job_id":       "3a8f2c1d-7b4e-4f9a-b2d6-1c5e8f3a9b7d",
  "status":       "queued",
  "image_url":    null,
  "cost":         null,
  "error":        null,
  "queued_at":    "2025-01-15T10:23:44Z",
  "started_at":   null,
  "completed_at": null,
  "created_at":   "2025-01-15T10:23:44Z"
}

{
  "job_id":       "3a8f2c1d-7b4e-4f9a-b2d6-1c5e8f3a9b7d",
  "status":       "completed",
  "image_url":    "https://your-project.supabase.co/storage/v1/object/public/generated-images/user-id/3a8f2c1d-xxxx.png",
  "cost":         "$0.03",
  "error":        null,
  "queued_at":    "2025-01-15T10:23:44Z",
  "started_at":   "2025-01-15T10:23:46Z",
  "completed_at": "2025-01-15T10:24:18Z",
  "created_at":   "2025-01-15T10:23:44Z"
}

{
  "job_id":       "9b3c1a2d-4f8e-4c7b-a1e5-2d9f6b4a8c3e",
  "status":       "failed",
  "image_url":    null,
  "cost":         null,
  "error":        "Provider request timed out after 180s.",
  "queued_at":    "2025-01-15T10:30:00Z",
  "started_at":   "2025-01-15T10:30:02Z",
  "completed_at": null,
  "created_at":   "2025-01-15T10:30:00Z"
}

{
  "error": "Insufficient wallet balance."
}

// Some errors also include a machine-readable code:
{
  "error": "Insufficient wallet balance.",
  "code":  "INSUFFICIENT_BALANCE"
}

// ── SharkAPI — complete JavaScript / Node.js example ──────────────

const SHARKAPI_KEY = process.env.SHARKAPI_KEY; // sk_live_...
const BASE_URL     = "https://www.sharkapi.dev";

// 1. Submit a generation job
async function generateImage(prompt, options = {}) {
  const body = { prompt, variant: "1k" };

  // Optional: attach a reference image (base64 or URL, not both)
  if (options.imageBase64) body.image     = options.imageBase64;
  if (options.imageUrl)    body.image_url = options.imageUrl;

  const res = await fetch(`${BASE_URL}/api/v1/image`, {
    method: "POST",
    headers: {
      "X-API-Key": SHARKAPI_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error ?? `HTTP ${res.status}`);
  }

  return res.json(); // { job_id, status: "queued", poll_url, price_usd }
}

// 2. Poll until completed or failed
async function waitForJob(jobId, timeoutMs = 180_000) {
  const url      = `${BASE_URL}/api/v1/jobs/${jobId}`;
  const headers  = { "X-API-Key": SHARKAPI_KEY };
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(url, { headers });
    if (!res.ok) throw new Error(`Poll failed: HTTP ${res.status}`);

    const job = await res.json();

    if (job.status === "completed") return job; // job.image_url is ready
    if (job.status === "failed")    throw new Error(job.error ?? "Job failed");

    // queued / processing — wait and retry
    await new Promise(r => setTimeout(r, 2000));
  }

  throw new Error("Job timed out after 3 minutes");
}

// 3. Full flow
async function main() {
  console.log("Submitting job...");
  const { job_id } = await generateImage(
    "A great white shark in bioluminescent deep ocean, cinematic, 8K"
  );

  console.log(`Job created: ${job_id} — polling...`);
  const job = await waitForJob(job_id);

  console.log("Done!");
  console.log("Image URL:", job.image_url);
  console.log("Cost:     ", job.cost);
}

main().catch(console.error);

# ── SharkAPI — complete Python example ────────────────────────────
import os, time, httpx

SHARKAPI_KEY = os.environ["SHARKAPI_KEY"]  # sk_live_...
BASE_URL     = "https://www.sharkapi.dev"

def generate_image(prompt: str, image_path: str | None = None, image_url: str | None = None) -> dict:
    """Submit a generation job. Returns the job dict with job_id."""
    headers = {
        "X-API-Key": SHARKAPI_KEY,
        "Content-Type": "application/json",
    }
    body = {"prompt": prompt, "variant": "1k"}

    if image_path:
        import base64
        with open(image_path, "rb") as f:
            body["image"] = base64.b64encode(f.read()).decode()
    elif image_url:
        body["image_url"] = image_url

    res = httpx.post(f"{BASE_URL}/api/v1/image", headers=headers, json=body, timeout=30)
    res.raise_for_status()
    return res.json()  # { job_id, status, poll_url, price_usd }


def wait_for_job(job_id: str, timeout: int = 180) -> dict:
    """Poll until completed or failed. Returns the completed job dict."""
    url      = f"{BASE_URL}/api/v1/jobs/{job_id}"
    headers  = {"X-API-Key": SHARKAPI_KEY}
    deadline = time.time() + timeout

    while time.time() < deadline:
        res = httpx.get(url, headers=headers, timeout=10)
        res.raise_for_status()
        job = res.json()

        if job["status"] == "completed":
            return job  # job["image_url"] is ready
        if job["status"] == "failed":
            raise RuntimeError(job.get("error") or "Job failed — no charge applied")

        time.sleep(2)  # queued / processing — keep polling

    raise TimeoutError("Job timed out after 3 minutes")


# Full flow
if __name__ == "__main__":
    print("Submitting job...")
    job_info = generate_image(
        "A great white shark in bioluminescent deep ocean, cinematic, 8K"
    )
    job_id = job_info["job_id"]
    print(f"Job created: {job_id} — polling...")

    job = wait_for_job(job_id)
    print("Done!")
    print("Image URL:", job["image_url"])
    print("Cost:     ", job["cost"])

#!/bin/bash
# ── SharkAPI — complete shell script example ──────────────────────

TOKEN="sk_live_••••••••"
BASE="https://www.sharkapi.dev"

# 1. Submit job
RESPONSE=$(curl -s -X POST "$BASE/api/v1/image" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A great white shark in bioluminescent deep ocean, cinematic, 8K"}')

JOB_ID=$(echo "$RESPONSE" | grep -o '"job_id":"[^"]*"' | cut -d'"' -f4)
echo "Job created: $JOB_ID"

# 2. Poll every 2 seconds
while true; do
  POLL=$(curl -s "$BASE/api/v1/jobs/$JOB_ID" \
    -H "X-API-Key: $TOKEN")

  STATUS=$(echo "$POLL" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ]; then
    echo "Image URL: $(echo $POLL | grep -o '"image_url":"[^"]*"' | cut -d'"' -f4)"
    break
  fi

  if [ "$STATUS" = "failed" ]; then
    echo "Job failed — no charge applied"
    break
  fi

  sleep 2
done