cURL Examples

Replace pxsk_your_key with your actual API key in every example. The base URL is https://api.picxstudio.com/v1.

Generate image#

curl -X POST https://api.picxstudio.com/v1/images/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a beautiful sunset over the ocean, cinematic lighting",
    "model": "gemini-3.1-flash-image-preview",
    "size": "2K",
    "aspect_ratio": "16:9"
  }'

Response — 200 OK

{
  "id": "img_1317c7d9b20a",
  "url": "https://cdn.picxstudio.com/api/generated/image_abc123.png",
  "model": "gemini-3.1-flash-image-preview",
  "size": "2K",
  "aspect_ratio": "16:9",
  "credits_used": 53,
  "created_at": "2026-08-14T09:52:37Z"
}

Edit image#

curl -X POST https://api.picxstudio.com/v1/images/edit \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "make the colors more vibrant and add a subtle glow effect",
    "image_urls": ["https://cdn.picxstudio.com/api/generated/image_abc123.png"],
    "model": "gemini-3.1-flash-image-preview",
    "size": "1K"
  }'

Response — 200 OK

{
  "id": "img_02b1b26add59",
  "url": "https://cdn.picxstudio.com/api/edited/image_def456.png",
  "model": "gemini-3.1-flash-image-preview",
  "size": "1K",
  "credits_used": 35,
  "created_at": "2026-08-14T09:53:17Z"
}

Generate video (async)#

# 1. Submit the async job
curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cat stretching and yawning on a sunny windowsill",
    "model": "fal-ai/bytedance/seedance/v2",
    "duration": 5,
    "resolution": "720p",
    "sound": true
  }'

Response — 202 Accepted

{
  "id": "903c6150-060b-4b3e-bb15-79b7f56f58bc",
  "status": "pending",
  "type": "video",
  "model": "fal-ai/bytedance/seedance/v2",
  "poll_url": "/v1/generations/903c6150-060b-4b3e-bb15-79b7f56f58bc",
  "events_url": "/v1/generations/903c6150-060b-4b3e-bb15-79b7f56f58bc/events",
  "webhook": { "mode": "none", "id": null, "url": null, "events": [] }
}

# 2. Poll the generation until it completes
curl https://api.picxstudio.com/v1/generations/903c6150-060b-4b3e-bb15-79b7f56f58bc \
  -H "Authorization: Bearer pxsk_your_key"

Response — completed

{
  "id": "903c6150-060b-4b3e-bb15-79b7f56f58bc",
  "status": "completed",
  "type": "video",
  "model": "fal-ai/bytedance/seedance/v2",
  "output_url": "https://cdn.picxstudio.com/videos/903c6150.mp4",
  "credits_used": 75,
  "created_at": "2026-08-14T09:54:00Z",
  "completed_at": "2026-08-14T09:55:50Z"
}

Video with inline webhook#

Bind a webhook so your server is notified on completion:

curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cat jumping off a table",
    "model": "fal-ai/bytedance/seedance/v2",
    "duration": 5,
    "resolution": "480p",
    "webhook": { "url": "https://your-server.com/webhook" }
  }'

Video modes#

POST /v1/videos/generate takes a mode selecting what drives the render. Each mode has its own required inputs. Every mode except lipsync requires a non-empty prompt; duration, resolution, and sound are sent and priced for every mode, including lipsync.

# image — animate a single source image (needs prompt + image_url)
curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "image",
    "prompt": "slow zoom out, gentle wind",
    "image_url": "https://cdn.picxstudio.com/uploads/api/scene.png",
    "duration": 5,
    "resolution": "720p"
  }'

# reference — guide the render with up to 10 reference images (needs prompt + reference_urls)
curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "reference",
    "prompt": "the same character walking through a market",
    "reference_urls": [
      "https://cdn.picxstudio.com/uploads/api/ref1.png",
      "https://cdn.picxstudio.com/uploads/api/ref2.png"
    ],
    "duration": 5
  }'

# frames — interpolate from a start frame (needs prompt + start_frame_url; end_frame_url optional)
curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "frames",
    "prompt": "smooth transition between the two frames",
    "start_frame_url": "https://cdn.picxstudio.com/uploads/api/first.png",
    "end_frame_url": "https://cdn.picxstudio.com/uploads/api/last.png",
    "duration": 5
  }'

# extend — continue an existing video (needs prompt + source_video_url)
curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "extend",
    "prompt": "the car keeps driving down the coast road",
    "source_video_url": "https://cdn.picxstudio.com/uploads/api/clip.mp4",
    "duration": 5
  }'

# lipsync — drive the lips from an audio track (needs source_video_url + audio_url; NO prompt)
# duration/resolution/sound are still sent because the job is priced from them.
curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "lipsync",
    "source_video_url": "https://cdn.picxstudio.com/uploads/api/speaker.mp4",
    "audio_url": "https://cdn.picxstudio.com/uploads/api/voiceover.mp3",
    "duration": 5,
    "resolution": "720p",
    "sound": true
  }'

# edit — edit a source video guided by an image (needs prompt + source_video_url + image_url)
curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "edit",
    "prompt": "restyle the scene as a watercolor painting",
    "source_video_url": "https://cdn.picxstudio.com/uploads/api/clip.mp4",
    "image_url": "https://cdn.picxstudio.com/uploads/api/style.png",
    "duration": 5
  }'

Each of these returns the same 202 Accepted body shown under Generate video (async) above; poll GET /v1/generations/{id} for the result.

Stream events via SSE#

Real-time status updates without polling:

curl -N https://api.picxstudio.com/v1/generations/903c6150-060b-4b3e-bb15-79b7f56f58bc/events \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Accept: text/event-stream"

Each SSE frame is a JSON snapshot. The stream closes when the job reaches a terminal status.

Templates#

Search the public template catalogue (~50,000 approved templates). Requires an API key; charges no credits.

# Search "golden hour", image only, first page
curl "https://api.picxstudio.com/v1/templates?q=golden%20hour&media_type=image&limit=30&offset=0" \
  -H "Authorization: Bearer pxsk_your_key"

# Topic bucket + repeatable tags (any-match) + trending sort
curl "https://api.picxstudio.com/v1/templates?topic=fashion&tags=portrait&tags=studio&trending=true" \
  -H "Authorization: Bearer pxsk_your_key"

# Fetch one template by id
curl https://api.picxstudio.com/v1/templates/10423 \
  -H "Authorization: Bearer pxsk_your_key"

Response — 200 OK

{
  "templates": [
    {
      "id": "10423",
      "title": "Golden hour portrait",
      "prompt": "a portrait bathed in warm golden-hour light, shallow depth of field",
      "media_type": "image",
      "topic": null,
      "tags": ["portrait", "aesthetic"],
      "target_model": "gemini-3.1-flash-image-preview",
      "preview_url": "https://cdn.picxstudio.com/templates/10423/preview.jpg",
      "thumbnail_url": "https://cdn.picxstudio.com/templates/10423/thumb.jpg",
      "is_featured": true,
      "likes": 1284
    }
  ],
  "total": 31,
  "limit": 30,
  "offset": 0
}

total is an estimate, not a count (no COUNT is run over the ~50k rows). It only signals whether another page exists. Page by increasing offset until a page returns fewer than limit templates. Also note: the topic field on every row is always null (topic is a query-time keyword filter, not a stored column), and prompt is null on premium/gated templates by design — null means gated, not missing. See Templates for the full field reference.

List models#

# All models (public — no auth required)
curl https://api.picxstudio.com/v1/models

# Filter by type
curl "https://api.picxstudio.com/v1/models?type=video"
curl "https://api.picxstudio.com/v1/models?type=image"

Account and usage#

# Account info
curl https://api.picxstudio.com/v1/account/me \
  -H "Authorization: Bearer pxsk_your_key"

# Usage stats
curl "https://api.picxstudio.com/v1/account/usage?period=30d" \
  -H "Authorization: Bearer pxsk_your_key"

Generations#

# List generations (with optional filters)
curl "https://api.picxstudio.com/v1/generations?type=video&limit=10" \
  -H "Authorization: Bearer pxsk_your_key"

# Cancel a pending generation
curl -X DELETE https://api.picxstudio.com/v1/generations/GENERATION_ID \
  -H "Authorization: Bearer pxsk_your_key"

Webhooks#

# Create a webhook
curl -X POST https://api.picxstudio.com/v1/webhooks \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["generation.completed", "generation.failed"]
  }'
# Response includes "secret": "whsec_..." — save it immediately

# List webhooks
curl https://api.picxstudio.com/v1/webhooks \
  -H "Authorization: Bearer pxsk_your_key"

# Test a webhook (sends a synthetic event)
curl -X POST https://api.picxstudio.com/v1/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer pxsk_your_key"

# View delivery history
curl https://api.picxstudio.com/v1/webhooks/WEBHOOK_ID/deliveries \
  -H "Authorization: Bearer pxsk_your_key"

# Redeliver a failed delivery
curl -X POST https://api.picxstudio.com/v1/webhooks/deliveries/DELIVERY_ID/redeliver \
  -H "Authorization: Bearer pxsk_your_key"

# Delete a webhook
curl -X DELETE https://api.picxstudio.com/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer pxsk_your_key"

Error responses#

All errors return JSON with a detail field:

{
  "detail": "Invalid API key"
}

Status	Meaning
401	Key missing, malformed, or revoked.
403	Key lacks the scope for this operation.
404	Resource does not exist.
422	Invalid parameters.
429	Rate limit exceeded. Check the Retry-After header.
500	Server error. Safe to retry.