Endpoints

POST — Generate Image

Submit an image generation job. Returns a job_id immediately — poll the Job Status endpoint until complete.

Overview

POSThttps://api.sharkapi.dev/v1/generate

This endpoint is fully async. It does not wait for image generation to complete. Instead, it returns a job_id that you use to poll for the result every 2 seconds.

ℹ

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

Request

Headers

Parameter	Type	Required	Description
Authorization	string	Required	Bearer token. 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.
mode	string	Required	Generation mode. Must be "1k" (1024×1024) or "2k" (2048×2048).
image	string	Optional	Base64-encoded source image for image-to-image generation. JPEG or PNG, max 10MB.
image_strength	number	Optional	How strongly the source image influences the output. Range 0.0–1.0. Default: 0.5.

Response

HTTP 202 Accepted on success.

Parameter	Type	Required	Description
job_id	string	Required	Unique identifier for this job. Use with GET /v1/jobs/:id to poll status.
status	string	Required	Initial job status. Always "queued" on creation.
estimated_cost	string	Required	Estimated cost of this job (e.g. "$0.30"). Final cost confirmed on completion.
poll_url	string	Required	Convenience URL for polling this job's status.
created_at	string	Required	ISO 8601 timestamp of job creation.

Response

json

{
  "job_id":         "job_8f2a9d3c",
  "status":         "queued",
  "estimated_cost": "$0.02",
  "poll_url":       "https://api.sharkapi.dev/v1/jobs/job_8f2a9d3c",
  "created_at":     "2024-01-15T10:23:44Z"
}

Modes

mode: "1k"$0.01

1024 × 1024

Fast standard resolution. Great for prototyping and high-volume use.

mode: "2k"$0.02

2048 × 2048

High-resolution output. Ideal for print and detail-critical applications.

Image input (img2img)

Pass a Base64-encoded image in the image field to guide generation using a reference image. Supported formats: JPEG, PNG. Maximum size: 10MB.

The image_strength parameter (0.0–1.0) controls how much the source image influences the output. Higher values preserve more of the original image.

Image-to-image request

bash

curl -X POST https://api.sharkapi.dev/v1/generate \
  -H "Authorization: Bearer sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "2k",
    "prompt": "Transform into a watercolor painting",
    "image": "'"$(base64 -w 0 ./input.jpg)"'",
    "image_strength": 0.6
  }'

Examples

Text-only (cURL)

bash

curl -X POST https://api.sharkapi.dev/v1/generate \
  -H "Authorization: Bearer sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "2k",
    "prompt": "A great white shark swimming through bioluminescent waters, cinematic, 8K"
  }'

JavaScript / Node.js

javascript

async function generateImage(prompt, mode = "2k") {
  const res = await fetch("https://api.sharkapi.dev/v1/generate", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SHARKAPI_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ prompt, mode }),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error.message);
  }

  const { job_id } = await res.json();
  return job_id;
}

Errors

Parameter	Type	Required	Description
400 Bad Request	HTTP	Optional	Invalid or missing request body fields.
402 Payment Required	HTTP	Optional	Insufficient wallet balance. Top up before retrying.
403 Forbidden	HTTP	Optional	Token is revoked or account is suspended.
422 Unprocessable Entity	HTTP	Optional	Prompt or image failed content moderation check.
429 Too Many Requests	HTTP	Optional	Rate limit exceeded. Slow down your requests.
503 Service Unavailable	HTTP	Optional	Generation service is temporarily unavailable. Retry after 30 seconds.