Endpoints

POST — Generate Image

Submit an image generation job. Returns a job_id immediately — then poll GET /api/v1/jobs/:id every 2 seconds until the result is ready.

Overview

POSThttps://www.sharkapi.dev/api/v1/image

This endpoint is fully asynchronous. It does not wait for image generation to finish. Instead it queues the job and returns a job_id you use to poll for the result. Generation typically takes 30 – 120 seconds.

ℹ

Your wallet is only charged when a job reaches status: "completed" and an image_url is returned. Failed or moderated jobs are never charged.

Request

Headers

Parameter	Type	Required	Description
Authorization	string	Required	Your API key. Format: "Bearer sk_live_..."
Content-Type	string	Required	"application/json"

Body parameters

Parameter	Type	Required	Description
prompt	string	Required	Text description of the image to generate. Max 2000 characters.
variant	string	Optional	Resolution variant. Currently only "1k" (1024×1024) is available. Defaults to "1k".
image	string	Optional	Base64-encoded reference image for image-to-image generation. JPEG, PNG, or WebP. Max 10 MB. Cannot be combined with image_url.
image_url	string	Optional	Publicly accessible URL of a reference image. Max 10 MB. Cannot be combined with image.

⚠

image and image_url are mutually exclusive — send one or the other, never both.

Sending an image (image-to-image)

You can guide generation with a reference image in two ways:

Option A — Base64

Encode your image file as base64 and pass it in the image field. You can include or omit the data:image/...;base64, prefix — both work. Supported formats: JPEG, PNG, WebP. Max size: 10 MB.

Base64 image input

bash

# Encode your image to base64 first
IMAGE_B64=$(base64 -w 0 ./reference.jpg)

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

Option B — URL

Pass a publicly accessible URL in the image_url field. The URL must be reachable from our servers. Private or authenticated URLs will fail — use base64 instead.

URL image input

bash

curl -X POST https://www.sharkapi.dev/api/v1/image \
  -H "Authorization: Bearer sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transform into a watercolor painting",
    "variant": "1k",
    "image_url": "https://your-cdn.com/reference.jpg"
  }'

ℹ

We mirror both inputs to our own storage before sending to the generation engine, so your original file or URL is never exposed to third parties.

Response

HTTP 202 Accepted on success. The job has been queued.

Parameter	Type	Required	Description
job_id	string	Required	Unique identifier for this job. Use with GET /api/v1/jobs/:id to poll for the result.
status	string	Required	Always "queued" immediately after creation.
poll_url	string	Required	Relative URL to poll for job status.
price_usd	number	Required	Cost of this job in USD (e.g. 0.03). Charged only on successful completion.
created_at	string	Required	ISO 8601 timestamp of job creation.

202 Response

json

{
  "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"
}

Examples

Text-only (cURL)

bash

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

JavaScript / Node.js

javascript

async function generateImage(prompt, imageBase64 = null) {
  const body = { prompt, variant: "1k" };
  if (imageBase64) body.image = imageBase64;

  const res = await fetch("https://www.sharkapi.dev/api/v1/image", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SHARKAPI_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error ?? "Request failed");
  }

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

const job = await generateImage("A shark surfing a neon wave");
console.log(job.job_id); // poll this next

Python

python

import httpx, base64

def generate_image(prompt: str, image_path: str | None = None) -> dict:
    headers = {
        "Authorization": f"Bearer {SHARKAPI_KEY}",
        "Content-Type": "application/json",
    }
    body = {"prompt": prompt, "variant": "1k"}

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

    res = httpx.post(
        "https://www.sharkapi.dev/api/v1/image",
        headers=headers,
        json=body,
        timeout=30,
    )
    res.raise_for_status()
    return res.json()  # { "job_id": "...", "status": "queued", ... }

Errors

Parameter	Type	Required	Description
400 Bad Request	HTTP	Optional	Missing or invalid body fields (e.g. no prompt, both image and image_url sent).
401 Unauthorized	HTTP	Optional	Missing or invalid API key.
402 Payment Required	HTTP	Optional	Insufficient wallet balance. Top up your account before retrying.
403 Forbidden	HTTP	Optional	API key is revoked or account is suspended.
422 Unprocessable Entity	HTTP	Optional	No active model for the requested variant. Only "1k" is currently available.
500 Internal Server Error	HTTP	Optional	Server-side error. Retry after a few seconds.