Automate image extraction with the ImageExtract API

ImageExtract product guide · Updated September 20, 2026

Start with a project API key

Use a plan with API access and create a project key. Keep it on a trusted server or in an environment variable, never in public browser code. The API overview links to the current contract and authentication examples.

Create a job and keep its identifier

POST a public URL to /api/v1/jobs using Bearer authentication. A successful creation returns 202 and a job_id. Save this identifier so a network interruption does not force you to create another extraction.

Poll with bounded retries

Read the job status until it completes or fails. Use a bounded wait, backoff, and Retry-After where supplied. A timeout in your client does not mean the remote job failed; inspect the existing job before retrying creation.

Fetch results and prepare downloads

Read the job result after completion. Use the documented export flow for packaged files, wait for the export to finish, and download before expiry. Handle an expired export distinctly from a failed extraction.

Keep integrations observable

Record status, duration, and error categories without logging API keys or sensitive source data. For webhook integrations, follow the current signature and retry documentation, and make handlers idempotent. See the runnable JavaScript quickstart and Python request example below.

API examples

Use a project key with API access. Replace the sample source URL with a public page you are permitted to process. Keep the key in your server environment.

JavaScript: extraction through download

const baseUrl = 'https://imageextract.com'
const apiKey = process.env.IMAGEEXTRACT_API_KEY

async function request(path, options = {}) {
  const response = await fetch(baseUrl + path, {
    signal: AbortSignal.timeout(30000),
    ...options,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      ...(options.headers ?? {}),
    },
  })
  if (!response.ok) throw new Error(await response.text())
  return response
}

async function sleep(ms) {
  await new Promise((resolve) => setTimeout(resolve, ms))
}

const create = await request('/api/v1/jobs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({ type: 'url', input: 'https://example.com' }),
}).then((response) => response.json())

const jobDeadline = Date.now() + 5 * 60 * 1000
let job
do {
  if (Date.now() > jobDeadline) throw new Error("Wait timed out; check the existing job_id before creating another job")
  await sleep(3000)
  job = await request(`/api/v1/jobs/${create.job_id}`).then((response) => response.json())
} while (job.status === 'queued' || job.status === 'processing' || job.status === 'pending')

if (job.status !== 'done') throw new Error(job.error ?? 'Extraction failed')

const result = await request(`/api/v1/jobs/${create.job_id}/result`).then((response) => response.json())
const createdExport = await request(`/api/v1/jobs/${create.job_id}/exports`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ template: 'zip' }),
}).then((response) => response.json())

const exportDeadline = Date.now() + 5 * 60 * 1000
let exportStatus = createdExport
while (exportStatus.status === 'queued' || exportStatus.status === 'processing') {
  if (Date.now() > exportDeadline) throw new Error("Export wait timed out; check the existing export ID")
  await sleep(3000)
  exportStatus = await request(`/api/v1/jobs/${create.job_id}/exports/${createdExport.id}`).then((response) => response.json())
}

if (exportStatus.status !== 'done') throw new Error(exportStatus.error ?? 'Export failed')

const zip = await request(`/api/v1/jobs/${create.job_id}/exports/${createdExport.id}/download`)
console.log({ images: result.image_count, expires_at: exportStatus.expires_at, bytes: Number(zip.headers.get('content-length') ?? 0) })

Python: create a job

import json, os, urllib.request

request = urllib.request.Request(
    "https://imageextract.com/api/v1/jobs",
    data=json.dumps({"type": "url", "input": "https://example.com"}).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["IMAGEEXTRACT_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request, timeout=30) as response:
    job = json.load(response)
print(job["job_id"])

The Python example creates a job only. Keep its ID and follow the reference to poll status, retrieve results, and prepare an export. Handle HTTP errors and a bounded waiting period in production.