"""Pickshot API client v1.1.0 (Python 3.10+, standard library only). API/MCP use credits, independently of website promotions and membership. Every generation uses credits; there is no free trial or membership inclusion. """ import json import time import uuid import urllib.request import urllib.error class PickshotError(Exception): def __init__(self, status, data, request_key=None): super().__init__(data.get('error', f'Pickshot HTTP {status}')) self.status, self.data, self.request_key = status, data, request_key class Pickshot: def __init__(self, api_key, base_url='https://pickshot.ai/api/v1', timeout=180): if not api_key: raise ValueError('A Pickshot API key is required') self.api_key, self.base, self.timeout = api_key, base_url.rstrip('/'), timeout def request(self, path, method='GET', body=None, idempotency_key=None): headers = {'Authorization': 'Bearer ' + self.api_key} if body is not None: headers['Content-Type'] = 'application/json' if idempotency_key: headers['Idempotency-Key'] = idempotency_key payload = json.dumps(body).encode() if body is not None else None for attempt in range(4): req = urllib.request.Request(self.base + path, data=payload, headers=headers, method=method) try: with urllib.request.urlopen(req, timeout=self.timeout) as response: return json.load(response) except urllib.error.HTTPError as error: try: data = json.loads(error.read()) except ValueError: data = {'error': f'HTTP {error.code}'} retry = error.code == 429 or error.code >= 500 or (error.code == 409 and data.get('error') == 'request_in_progress') try: delay = max(0, float(error.headers.get('retry-after') or 0), float(data.get('retry_after') or 0)) or 2 except (TypeError, ValueError): delay = 2 # Return long backoffs to the caller instead of retrying early. if attempt < 3 and retry and delay <= 30 and (method == 'GET' or idempotency_key): time.sleep(delay) continue raise PickshotError(error.code, data, idempotency_key) from None except (urllib.error.URLError, TimeoutError) as error: if attempt == 3 or not (method == 'GET' or idempotency_key): raise PickshotError(0, {'error': 'transport_error'}, idempotency_key) from error time.sleep(attempt + 1) def confirm_adult(self, age): if age is not True: raise ValueError('Explicit age confirmation is required') return self.request('/me/adult-confirm', method='POST', body={'age': True}) def balance(self): return self.request('/me') def models(self): return self.request('/models') def usage(self, days=30): """What this key and account have really used over 7 or 30 days (calls for this key, generations and credits for the account).""" return self.request('/usage?days=' + str(int(days))) def gpu_status(self): return self.request('/gpu/status') def gpu_availability(self): return self.request('/gpu/availability') def estimate(self, kind, request): self._kind(kind) return self.request('/estimate', 'POST', {'kind': kind, 'request': {'use_trial': False, **request}}) def create(self, kind, request, *, max_credits, idempotency_key=None): self._kind(kind) if isinstance(max_credits, bool) or not isinstance(max_credits, int) or max_credits < 0: raise ValueError('max_credits must be a nonnegative integer from a current estimate') key = idempotency_key or uuid.uuid4().hex return self.request('/' + kind, 'POST', {'use_trial': False, **request, 'max_credits': max_credits}, key) def job(self, job_id): from urllib.parse import quote return self.request('/jobs/' + quote(job_id, safe='')) def wait(self, job_id, timeout=600, interval=2.5): until = time.monotonic() + timeout while time.monotonic() < until: job = self.job(job_id) if job['status'] in ('done', 'failed', 'canceled'): return job time.sleep(max(.5, interval)) raise TimeoutError(f'Timed out waiting for {job_id}; keep polling this job rather than creating it again') @staticmethod def _kind(kind): if kind not in ('images', 'videos', 'audio'): raise ValueError('kind must be images, videos or audio')