API v1.0

CyberStock API

Programmatic access to the CyberStock AI Engine for stock photo and video metadata. Titles, descriptions, keywords, and Selling Score in one API call, powered by real buyer searches.

Get Started·Process Endpoint·Code Examples·Error Handling

Base URL

Copy your exact base URL from Account → API (inside the app). Use it as CYBERSTOCK_API_BASE.

bash

export CYBERSTOCK_API_BASE="https://<your-api-base>/functions/v1/api-gateway"

Overview

The CyberStock API lets you process images and videos and get stock-ready metadata: titles, descriptions, keywords, categories, and Selling Score. It uses the same AI Engine as the CyberStock web app.

Photo & Video

Process JPG, PNG, WebP, TIFF, MP4, MOV, and more

Metadata Generation

Generate titles, descriptions, and up to 50 keywords

Scoring

Get selling scores to evaluate commercial potential

Authentication

All API requests require an API key sent via the X-API-Key header.

Getting Your API Key

Sign in to CyberStock and go to your Account panel
Click the API tab
Click Generate Key. Your key starts with cs_live_
Copy and save the key securely. It's shown only once

Header

X-API-Key: cs_live_YOUR_API_KEY_HERE

Plan Requirement: API access requires a Pro, Studio, or Unlimited subscription, or a one-time 60,000 or 120,000 credit top-up purchase. Rate limits vary by plan: Pro & 60k top-up (60 req/min), Studio & 120k top-up (120 req/min), Unlimited (300 req/min).

Endpoints

POST/v1/processProcess an image or video

GET/v1/accountGet account info and credits

GET/v1/sessionsList your API sessions

GET/v1/sessions/:idGet results for a specific session

POST /v1/process

Process a single image or video file and receive metadata generated by the CyberStock AI Engine. Provide the file either as a public URL or base64-encoded data.

Request Parameters

Parameter	Type	Description
`image_url`required	`string`	Public URL of the image or video to process. Provide this or `image_base64`.
`image_base64`	`string`	Base64-encoded file data. Use when the file isn't publicly accessible. Limit: `250,000` base64 characters (for larger files, use `image_url`).
`filename`	`string`	Original filename with extension (e.g., `"beach.jpg"`). Helps AI detect media type.
`language`	`string`	Output language code. Default: `"en"`. Examples: `"es"`, `"de"`, `"fr"`, `"ja"`.
`keywords_limit`	`number`	Maximum number of keywords to return. Default: `50`. Range: 1-50.
`keyword_mode`	`string`	`"single"` (default) for single-word keywords, or `"long-tail"` for multi-word phrases.
`platform`	`string`	Target stock platform. Options: `"shutterstock"`, `"adobe"`, `"alamy"`, `"getty"`, etc.
`media_type`	`string`	Override media type detection: `"image"`, `"video"`, or `"vector"`.
`max_description_chars`	`number`	Maximum characters for the description. Default: `480`.
`max_title_chars`	`number`	Maximum characters for the title. Default: `200`.
`editorial`	`boolean`	Enable editorial mode for news/documentary content. Default: `false`.
`editorial_seed`	`object`	Editorial context: `{"city":"NYC","country":"US","date":"2024-01-15"}`
`single_word_only`	`boolean`	Force strictly single-word keywords (no compounds). Default: `false`.
`allow_compound_keywords`	`boolean`	Allow multi-word compound keywords. Default: `false`.
`title_case`	`boolean`	Output title in Title Case (capitalize each major word). Default: `false` (sentence case).
`title_all_caps`	`boolean`	Output title in ALL CAPS. Default: `false`.

Response

JSON

{
  "ok": true,
  "session_id": "sess_12345",
  "image_id": "img_12345",
  "status": "ready",
  "metadata": {
    "title": "Golden sunset over tropical beach with palm trees",
    "description": "Stunning golden hour sunset illuminating a pristine tropical beach lined with swaying palm trees, calm turquoise waters reflecting warm amber light, creating a serene and idyllic paradise scene perfect for travel and vacation concepts.",
    "keywords": [
      "sunset", "beach", "tropical", "palm trees", "ocean",
      "golden hour", "paradise", "vacation", "travel", "seascape",
      "turquoise", "calm", "serene", "idyllic", "coastline"
    ],
    "category": "Nature/Landscapes",
    "media_type": "image"
  },
  "scores": {
    "selling_score": 87,
    "title_score": 92,
    "description_score": 89,
    "keyword_score": 85
  },
  "credits": {
    "used": true,
    "remaining": 742
  },
  "processing": {
    "duration_ms": 1247,
    "retryable": false
  }
}

Code Examples

Single File Processing

bash

export CYBERSTOCK_API_BASE="https://<your-api-base>/functions/v1/api-gateway"

curl -X POST "$CYBERSTOCK_API_BASE/v1/process" \
  -H "X-API-Key: cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "filename": "sunset-beach.jpg",
    "language": "en",
    "keywords_limit": 50,
    "keyword_mode": "single"
  }'

Batch Processing (Python)

python

import requests
import concurrent.futures

API_KEY = "cs_live_YOUR_KEY"
API_BASE = "https://<your-api-base>/functions/v1/api-gateway"
API_URL = f"{API_BASE}/v1/process"

files = [
    {"url": "https://example.com/photo1.jpg", "name": "photo1.jpg"},
    {"url": "https://example.com/photo2.jpg", "name": "photo2.jpg"},
    {"url": "https://example.com/video1.mp4", "name": "video1.mp4"},
]

def process_file(file):
    resp = requests.post(API_URL, json={
        "image_url": file["url"],
        "filename": file["name"],
        "language": "en",
        "keywords_limit": 50,
    }, headers={"X-API-Key": API_KEY})
    return resp.json()

# Process up to 5 files concurrently
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    results = list(executor.map(process_file, files))

for r in results:
    if r.get("ok"):
        print(f"{r['metadata']['title']}")

GET /v1/account

Check your current plan, credit balance, and account status.

bash

curl "$CYBERSTOCK_API_BASE/v1/account" \
  -H "X-API-Key: cs_live_YOUR_KEY"

JSON

{
  "ok": true,
  "account": {
    "email": "user@example.com",
    "plan": "pro",
    "api_access": true,
    "api_tier": "pro",
    "credits": 742,
    "credits_subscription": 500,
    "credits_topup": 242,
    "is_unlimited": false
  }
}

GET /v1/sessions

List your recent API processing sessions. Supports pagination via limit and offset (or page).

bash

curl "$CYBERSTOCK_API_BASE/v1/sessions?limit=100&offset=0" \
  -H "X-API-Key: cs_live_YOUR_KEY"

GET /v1/sessions/:id

Get processed results for a specific session, including full metadata for each file. Supports pagination for large sessions (CyberBatch sessions can hold up to 1 000 000 files).

bash

# First page (default limit=100, max=2000)
curl "$CYBERSTOCK_API_BASE/v1/sessions/<SESSION_ID>?limit=1000&offset=0" \
  -H "X-API-Key: cs_live_YOUR_KEY"

# Loop until pagination.has_more === false
curl "$CYBERSTOCK_API_BASE/v1/sessions/<SESSION_ID>?limit=1000&offset=1000" \
  -H "X-API-Key: cs_live_YOUR_KEY"

JSON

{
  "ok": true,
  "session": { "id": "...", "status": "completed", "total_images": 10219 },
  "pagination": {
    "total": 10219,
    "offset": 0,
    "limit": 1000,
    "returned": 1000,
    "has_more": true,
    "next_offset": 1000
  },
  "results": [ /* 1000 items */ ]
}

Parameter	Type	Default / Max	Description
`limit`	int	100 / 2000	Rows to return per call. Values above the ceiling are silently capped.
`offset`	int	0 / no cap	Number of rows to skip. Use `pagination.next_offset` from the previous response.
`page`	int	1	1-indexed alternative to `offset`. Ignored when `offset` is set.

Rate Limits

Rate limits depend on your subscription plan:

Plan	Requests / Minute	Max API Keys
Pro / 60k Top-Up	60	3
Studio / 120k Top-Up	120	3
Unlimited	300	3

When you exceed the limit, the API returns 429 RATE_LIMIT_EXCEEDED. Wait a few seconds and retry.

Error Reference

Status	Error Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key
401	`INVALID_API_KEY`	API key is revoked or doesn't exist
402	`INSUFFICIENT_CREDITS`	Not enough credits to process
403	`API_ACCESS_DENIED`	Plan doesn't include API access (need Pro+)
403	`SCOPE_DENIED`	API key doesn't have required scope
429	`RATE_LIMIT_EXCEEDED`	Too many requests per minute
400	`MISSING_INPUT`	No image_url or image_base64 provided
400	`INVALID_JSON`	Request body is not valid JSON
502	`PROCESSING_FAILED`	Internal processing error (retry)

Ready to get started?

Generate your API key and start processing files in minutes.