Skip to navigation
SDKs

SDKs

Start with a published SDK package for your server language.

Release status. API 1.0.0-rc.1 is a release candidate: request and response shapes may still change before the stable release. SDK 0.2.2 is published as a Developer Preview (@morphiaone/sdk on npm and morphiaone on PyPI).

Both clients take the API base URL, https://api.morphiaone.ai, and an API key from your server environment; neither has a built-in default host.

Choose your SDK

TypeScript
Developer Preview

npm install --save-exact @morphiaone/sdk@0.2.2

Node.js 20 or newer. Typed, ESM, no runtime dependencies.

Python
Developer Preview

python -m pip install morphiaone==0.2.2

Python 3.11 or newer, with a sync and an async client.

REST
Release candidate

https://api.morphiaone.ai

Plain HTTP with an X-API-Key header, from any language.

Pin the published version in deployment files:

npm install --save-exact @morphiaone/sdk@0.2.2
python -m pip install morphiaone==0.2.2

Both packages are server-side clients. Keep API keys in your server’s secret store; never include one in a browser bundle or mobile app. A browser or mobile client should call your backend, which authenticates your user before it calls MorphiaOne. See the BFF pattern.

One client, one job flow

Each client exposes Assets, Skin Analysis, Makeup Try-On, Hair Color Try-On, Jobs, Usage and Credits. Product submissions are asynchronous: upload input images as Assets, submit a request, persist the returned Job id, then wait or poll. Read output only after the Job succeeds; fetch result Asset bytes before their expiry.

The SDKs add typed responses, request retries, Retry-After handling, idempotency keys, job waiting, and client-specific error classes. Pass a stable idempotency key derived from your own operation when a retry must survive a process restart. See Idempotency, Jobs, and Retries and backoff.

Use the full guides for method signatures, async support, timeout behavior, and examples:

Features that need the next SDK release

FeatureTypeScriptPythonDocumented in
List jobs and assets, one page or every pagejobs.list, jobs.listAll, assets.list, assets.listAlljobs.list, jobs.list_all, assets.list, assets.list_allJobs, Assets
Cancel and deletejobs.cancel, jobs.delete, assets.deletejobs.cancel, jobs.delete, assets.deleteJobs, Assets
cancelled statusJobCancelledError from jobs.waitJobCancelledError from jobs.waitJobs
Credit balancecredits.balance()credits.balance()Usage and credits
Webhook signature verificationverifyWebhook, WebhookSignatureErrorwebhooks.verify, WebhookSignatureErrorWebhooks
Rate-limit metadataparseRateLimit, client.lastRateLimitparse_rate_limit, client.last_rate_limitRate limits
Error links and retryabilityerror.docUrl, error.retryableerror.doc_url, error.retryableRetries and backoff
Test mode markerslivemode, client.isTestModelivemode, client.is_test_modeTest mode

Upgrading needs one change in your code: handle cancelled wherever you switch over a job’s status. It is terminal and carries no output. No method is renamed or removed.

API and product status

Skin, Makeup, and Hair are available; your account is provisioned for the products in your agreement, and a key calls a product only if it carries that product’s scope. See product availability and the API overview before planning an integration.

The URL version, contract version, and package version answer different questions:

VersionWhere it appearsWhat it tracks
/v1API pathWire compatibility; a breaking API change requires a new path.
Contract versioninfo.version in OpenAPIChanges to the published contract, including additive changes.
SDK versionnpm and PyPI package versionChanges to the SDK package surface and behavior.

See Versioning for what may change and how you find out.