Documentation

SharkApi.dev Docs

Everything you need to integrate async image generation into your application.

Quick Start

Get your first image generated in under 5 minutes. You'll need an account, an API token, and at least $10 in your wallet — or use your 3 free trial generations.

Step 1 — Get your API token

After registering, go to Dashboard → API Tokens and copy your token. Keep it secret — treat it like a password.

Step 2 — Send a request & poll

Quick start

bash

# 1. Create a job
curl -X POST https://api.sharkapi.dev/v1/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"2k","prompt":"A shark swimming in neon-lit deep ocean"}'

# → { "job_id": "job_abc123", "status": "queued", "estimated_cost": "$0.02" }

# 2. Poll until complete (every 2 seconds)
curl https://api.sharkapi.dev/v1/jobs/job_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

# → { "status": "complete", "image_url": "https://cdn.sharkapi.dev/..." }

ℹ

The API is fully async. You receive a job_id immediately and poll the job status endpoint until status === "complete". Poll every 2 seconds.

Authentication

All API requests must include a Bearer token in the Authorization header.

Request header

http

Authorization: Bearer sk_live_••••••••••••••••••

Parameter	Type	Required	Description
Authorization	string	Required	Bearer token from your API Tokens page. Never expose this in client-side code.

⚠

Never include API tokens in client-side JavaScript or public repositories. Always call the API from your server or backend.

Request Flow

Every image generation follows the same async pattern:

POST /v1/generate

Submit job → receive job_id + estimated_cost

Check wallet

If insufficient balance → 402 error returned

GET /v1/jobs/:id

Poll every 2s → status: queued → processing

status: complete

image_url returned, wallet deducted

Endpoints

POST/v1/generate

Submit an image generation job

GET/v1/jobs/:id

Poll the status and result of a job

GET/v1/wallet/balance

Retrieve current wallet balance

GET/v1/usage

List historical requests and usage data

Error Handling

All errors follow a consistent JSON format. Check the Error Codes reference for the full list.

Error response

json

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your wallet balance is too low to process this request.",
    "status": 402
  }
}