Python & JavaScript SDK for AI Video

import { randomUUID } from "node:crypto";
import {
  PicX,
  PicXGenerationFailedError,
  PicXInsufficientCreditsError,
  PicXPollingTimeoutError,
} from "picx-ai";

const picx = new PicX(process.env.PICX_API_KEY);

try {
  const job = await picx.video.create(
    {
      prompt: "a cinematic product shot of a smartwatch, slow orbit",
      model: "fal-ai/bytedance/seedance/v2",
      duration: 5,
      resolution: "720p",
      sound: true,
      aspect_ratio: "16:9",
      callback_url: "https://your-app.com/api/picx-hook",
    },
    // Keep this key with your job row. A retry with it charges once.
    { idempotencyKey: randomUUID() },
  );
  console.log("Queued:", job.id, job.status);

  // The webhook delivers the result. Polling is the fallback.
  const asset = await job.wait({ pollIntervalMs: 5_000, timeoutMs: 900_000 });
  console.log(asset.url, asset.credits_used);
} catch (err) {
  if (err instanceof PicXInsufficientCreditsError) {
    console.error("Top up your credits first.");
  } else if (err instanceof PicXGenerationFailedError) {
    // Credits for this generation are refunded automatically.
    console.error(err.generationId, err.generationStatus, err.message);
  } else if (err instanceof PicXPollingTimeoutError) {
    // Not failed, only still running. Resume with generations.get(id).
    console.error("Still running:", err.generationId, err.lastStatus);
  } else {
    throw err;
  }
}

import os
import uuid

from picx import InsufficientCreditsError, JobFailedError, JobTimeoutError, PicX

with PicX(os.environ["PICX_API_KEY"]) as picx:
    try:
        job = picx.video.create(
            prompt="a cinematic product shot of a smartwatch, slow orbit",
            model="fal-ai/bytedance/seedance/v2",
            duration=5,
            resolution="720p",
            sound=True,
            aspect_ratio="16:9",
            callback_url="https://your-app.com/api/picx-hook",
            # Keep this key with your job row. A retry with it charges once.
            idempotency_key=str(uuid.uuid4()),
        )
        print("Queued:", job.id, job.status)

        # The webhook delivers the result. Polling is the fallback.
        asset = job.wait(timeout=900, poll_interval=5)
        print(asset.url, asset.credits_used)
    except InsufficientCreditsError:
        print("Top up your credits first.")
    except JobFailedError as exc:
        # Credits for this generation are refunded automatically.
        print(exc.generation_id, exc.status, exc)
    except JobTimeoutError as exc:
        # Not failed, only still running. Resume with generations.get(id).
        print("Still running:", exc.generation_id, exc.status)

curl -X POST https://api.picxstudio.com/v1/videos/generate \
  -H "Authorization: Bearer $PICX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt":"a cinematic product shot of a smartwatch, slow orbit","model":"fal-ai/bytedance/seedance/v2","duration":5,"resolution":"720p","sound":true,"aspect_ratio":"16:9","callback_url":"https://your-app.com/api/picx-hook"}'

# Answers 202 with an id. Poll it until status is completed or failed.
curl https://api.picxstudio.com/v1/generations/$GENERATION_ID \
  -H "Authorization: Bearer $PICX_API_KEY"

import { PicX } from "picx-ai";

const picx = new PicX(process.env.PICX_API_KEY);

export async function POST(req: Request) {
  // Deliveries are at-least-once. Retries reuse this id, so dedupe on it.
  const deliveryId = req.headers.get("x-picx-delivery");
  if (deliveryId && (await alreadyHandled(deliveryId))) {
    return new Response(null, { status: 204 });
  }

  const event = await req.json();

  // Read the result from the API with your key. Do not trust the POST body.
  const generation = await picx.generations.get(event.data.generation_id);

  if (generation.status === "completed") {
    await saveVideo(generation.id, generation.output_url, generation.credits_used);
  } else if (generation.status === "failed") {
    await markFailed(generation.id, generation.error_message);
  }

  return new Response(null, { status: 204 });
}

import os

from flask import Flask, request
from picx import PicX

app = Flask(__name__)
picx = PicX(os.environ["PICX_API_KEY"])


@app.post("/api/picx-hook")
def picx_hook():
    # Deliveries are at-least-once. Retries reuse this id, so dedupe on it.
    delivery_id = request.headers.get("X-PicX-Delivery")
    if delivery_id and already_handled(delivery_id):
        return "", 204

    event = request.get_json()

    # Read the result from the API with your key. Do not trust the POST body.
    generation = picx.generations.get(event["data"]["generation_id"])

    if generation.status == "completed":
        save_video(generation.id, generation.output_url, generation.credits_used)
    elif generation.status == "failed":
        mark_failed(generation.id, generation.error_message)

    return "", 204