Skip to main content

picsart-ai-sdk

Generate images, video, audio, and text with 100+ AI models — the Python counterpart of @picsart/ai-sdk (TypeScript), with the same public surface: snake_case names, async like the TypeScript client, Python 3.10+.

Documentation

Repository: github.com/PicsArt/ai-sdk-python

Quick start

pip install picsart-ai-sdk
import asyncio
import os

from picsart_ai_sdk import Model, catalog, create_client


async def main() -> None:
    async with create_client(api_key=os.environ["PICSART_API_KEY"], api_url="https://api.picsart.com") as ai:
        # Generate — model ids are plain strings, resolved server-side; no catalog load needed.
        result = await ai.generate("flux-2-pro", {"prompt": "a cat on mars"})
        print(result.url)

        text = await ai.generate_text("gemini-2.5-flash", {"prompt": "Name three colors"})
        print(text.text)

        # The local catalog accessors (Model / catalog / ai.validate) read the models catalog: load it once.
        await ai.init_model_catalog()
        catalog.all()  # every model
        catalog.find(output="video")  # video models only
        catalog.search("kling")  # by name / id / provider
        Model("flux-2-pro").meta()  # mode, provider, badges, …
        Model("flux-2-pro").params().to_schema()  # param schema
        print(Model("flux-2-pro").validate({"prompt": "a cat"}))  # ValidationResult(valid=True, errors=None)


asyncio.run(main())

Every generation rides the models-hub v1/models workflow: the server resolves the model, builds the vendor payload and normalizes the result. The catalog accessors raise ApiError 409 catalog_not_loaded until await ai.init_model_catalog(); generate() / generate_text() / run() / submit() never wait on it.

Authentication

Pass api_key and the SDK sends Authorization: Bearer <api_key> on every request. Apps that handle auth themselves can pass their own async fetch(url, init) -> httpx.Response instead (it wins over api_key):

ai = create_client(fetch=my_authenticated_fetch, api_url="https://api.picsart.com")

Or replace the requests altogether with a custom transport (execute, and optionally submit / poll / status / options) — the same contract as the TypeScript SdkTransport.

Async jobs, progress and cancellation

from picsart_ai_sdk import AbortController, GenerateOptions, GenerationEventType

generation_id = await ai.submit("kling-v3", {"prompt": "a drone shot over the sea"})

async with ai.subscribe("kling-v3", generation_id) as events:
    async for event in events:
        if event.type == GenerationEventType.Completed:
            print(event.result.url)

controller = AbortController()
job = asyncio.create_task(ai.generate("kling-v3", {"prompt": "…"}, GenerateOptions(signal=controller.signal)))
controller.abort()  # `await job` raises ApiError 499 `aborted`; `job.cancel()` works too

Failures are always ApiError (status, code, message), as in the TypeScript SDK.

More

  • Typed inputs — picsart_ai_sdk.model_types has one TypedDict per model (Flux2ProInput, …) plus TypedModelId, TextModelId, JsonModelId; it is regenerated from the models catalog on every catalog release.
  • Raw APIs — await ai.apis.run("vendor/v1/task", payload) runs any model API by name.
  • Catalogs — await ai.catalogs.voices(model) / avatars / templates: paged, cached, and hydrated into Model(id).params().
  • Drive — create_client(..., drive=DriveConfig(folder="AI")) saves generations to Picsart Drive and exposes ai.drive (folders, listing, save, reactions, get_generation).
  • Deep links — encode_deep_link_payload(model, context) / decode_deep_link_payload(encoded), compatible with the links the TypeScript SDK makes.
  • Credits — await ai.get_credits(model, params); catalog.pricing for credit ranges.
  • Service tier — GenerateOptions(service_tier="priority") pays the regular price and skips the limits of the user's discount (a concurrency limit that answers 429, and a wait after heavy use); the default "auto" uses the discount when one applies. Set it for every call with create_client(..., service_tier="priority"), and quote the same tier: await ai.get_credits(model, params, PriceOptions(service_tier="priority")).

Development

python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
ruff check . && ruff format --check . && mypy && pytest

scripts/generate_model_types.py regenerates model_types.py (PICSART_TOKEN, or --from-file a saved /v1/models-catalog response). tests/golden/ts-sdk.json holds cases recorded from the TypeScript SDK that this SDK must reproduce.

License

MIT

Metadata

Release files for picsart-ai-sdk 0.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for picsart-ai-sdk 0.17.0
File Size Uploaded Provenance Actions
picsart_ai_sdk-0.17.0.tar.gz 157.7 kB With provenance Details for picsart_ai_sdk-0.17.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for picsart-ai-sdk 0.17.0
File Interpreter ABI Platform Actions
picsart_ai_sdk-0.17.0-py3-none-any.whl Python 3 none any Details for picsart_ai_sdk-0.17.0-py3-none-any.whl

Total release size: 257.5 kB

Release files / picsart_ai_sdk-0.17.0.tar.gz

Download URL picsart_ai_sdk-0.17.0.tar.gz
Size 157.7 kB
Tags Source
SHA-256 checksum
How to use checksums
b602e0e5d133f3e33caf60ef6a633feedf017be3abfe09681441a2604ff6dbd7
BLAKE2b-256 checksum
How to use checksums
4afce961ea2ad2279c2053bdad6f9d2505661fd2bd43bb47ca8ed3ab86b30a16
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / picsart_ai_sdk-0.17.0-py3-none-any.whl

Download URL picsart_ai_sdk-0.17.0-py3-none-any.whl
Size 99.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b11bf8039547c94384ba63d25208769f02a878e72241dd293026448d901dc5a7
BLAKE2b-256 checksum
How to use checksums
4d3428072f1313c7980965759da2547515009bc580ee9dac9bd3a7b990e320c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for picsart-ai-sdk 0.17.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for picsart_ai_sdk-0.17.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page