API

Access WoopicX search and AI generation via API. All endpoints require an API key.

API Keys

Endpoints

All endpoints require X-API-Key header

POST/v1/generateGenerate image or video from prompt

GET/v1/generate/{task_id}Check generation status

POST/v1/search

GET/v1/asset/{uid}

GET/v1/collections

GET/v1/key-info

Generate

Generate AI images and videos from text prompts. Async — submit a request, then poll for the result.

1. Start generation

POST https://api.woopicx.com/v1/generate

Parameters

promptText description of what to generate (required)

type"image" or "video" (default: "image")

sizeImage size (default: 1024x1024). Options: 1024x1024, 1248x832, 832x1248, 1344x768, 768x1344, 1184x864, 864x1184, 1152x896, 896x1152, 1536x672

durationVideo duration in seconds, 2-10 (default: 4). Video only.

aspect_ratioVideo aspect ratio (default: "16:9"). Options: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3. Video only.

Response (202)

{
  "task_id": "api_5793db67-...",
  "asset_uid": "dd1aba2a-...",
  "status": "processing",
  "type": "image",
  "energy_cost": 1
}

2. Poll for result

GET https://api.woopicx.com/v1/generate/{task_id}

Poll every 3-5 seconds until status is completed or failed.

Response (completed - image)

{
  "task_id": "api_5793db67-...",
  "status": "completed",
  "type": "image",
  "asset_uid": "dd1aba2a-...",
  "url": "https://...presigned.../main.png",
  "thumb_url": "https://...presigned.../thumb.jpg",
  "width": 1024,
  "height": 1024
}

Response (completed - video)

{
  "task_id": "api_5793db67-...",
  "status": "completed",
  "type": "video",
  "asset_uid": "dd1aba2a-...",
  "url": "https://...presigned.../video.mp4",
  "thumb_url": "https://...presigned.../thumb.jpg",
  "width": 1280,
  "height": 720,
  "duration": 4,
  "aspect_ratio": "16:9"
}

Examples

Generate image:

curl -X POST "https://api.woopicx.com/v1/generate" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a red apple on white background"}'

Generate video:

curl -X POST "https://api.woopicx.com/v1/generate" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "video", "prompt": "ocean waves at sunset", "duration": 6, "aspect_ratio": "16:9"}'

Check status:

curl "https://api.woopicx.com/v1/generate/TASK_ID" \
  -H "X-API-Key: YOUR_KEY"

Cost: 1 energy per image, ceil(duration/2) energy per video (e.g. 4s video = 2 energy). Image generation takes 5-20 seconds, video 60-120 seconds. URLs are signed links valid for 7 days.

Search

POST https://api.woopicx.com/v1/search

Parameters

querySearch query (optional if collection specified)

limitResults per page (default: 50, max: 100)

offsetPagination offset (default: 0)

collectionFilter by collection

media_typeFilter by type: image, video, 3d

sortSort order: relevance, newest, rating

Response

Returns previews only. Use /v1/asset/{uid} to download.

{
  "results": [{
    "uid": "abc-123",
    "title": "Asset title",
    "thumb_url": ["https://..."],
    "preview_url": "https://...",
    "is_free": true,
    "media_type": "png",
    "collection": ["basic3d"]
  }],
  "total_found": 100
}

Examples

Search videos:

{"collection": "base-video", "limit": 10}

Search 3D assets:

{"collection": "basic3d", "limit": 10}

Search with query:

{"query": "office", "collection": "base-video", "limit": 10}

Asset

GET https://api.woopicx.com/v1/asset/{uid}

Returns asset metadata with main file URL. For paid assets, main_url is a signed URL valid for 7 days.

Parameters

formatFile format: png, svg, mp4 (optional, auto-detected)

Response

{
  "uid": "abc-123",
  "title": "Asset title",
  "media_type": "png",
  "is_free": true,
  "main_url": "https://images.woopicx.com/...",
  "preview_url": "https://...",
  "main_width": 1920,
  "main_height": 1080,
  "format": "png"
}

Premium Assets

Assets with is_free: false require active subscription. Returns 403 if no subscription.

Collections

GET https://api.woopicx.com/v1/collections

Returns list of available collections with asset counts. Requires API key.

Available Collections

baseimageGeneral images

base-videovideoStock videos

basic3d3d3D renders and objects

basic-greenimageGreen screen backgrounds

real-estateimageReal estate photos

glass-iconsimageGlass-style icons

abyssimageDark abstract visuals

lets-presentimagePresentation graphics

story-imageimageSocial media stories

tattooimageTattoo designs

mobile-phone-mockupimagePhone mockups

Rate Limits

Rate limit is set per API key (default: 100 requests/min). Need more? Contact us