> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.morphiaone.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.morphiaone.ai/_mcp/server.

# SDKs

> **Info**
>
> **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](/getting-started/quickstart)

Developer Preview

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

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

#### [Python](/sdks/python)

Developer Preview

`python -m pip install morphiaone==0.2.2`

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

#### [REST](/rest-api/onboarding)

Release candidate

`https://api.morphiaone.ai`

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

Pin the published version in deployment files:

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

```bash
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](/guides/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](/concepts/idempotency), [Jobs](/concepts/jobs), and
[Retries and backoff](/concepts/retries).

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

* [TypeScript SDK guide](/sdks/typescript)
* [Python SDK guide](/sdks/python)
* [REST onboarding](/rest-api/onboarding) for direct HTTP integrations

## Features that need the next SDK release

| Feature                                      | TypeScript                                                   | Python                                                         | Documented in                                      |
| -------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------- |
| List jobs and assets, one page or every page | `jobs.list`, `jobs.listAll`, `assets.list`, `assets.listAll` | `jobs.list`, `jobs.list_all`, `assets.list`, `assets.list_all` | [Jobs](/concepts/jobs), [Assets](/concepts/assets) |
| Cancel and delete                            | `jobs.cancel`, `jobs.delete`, `assets.delete`                | `jobs.cancel`, `jobs.delete`, `assets.delete`                  | [Jobs](/concepts/jobs), [Assets](/concepts/assets) |
| `cancelled` status                           | `JobCancelledError` from `jobs.wait`                         | `JobCancelledError` from `jobs.wait`                           | [Jobs](/concepts/jobs)                             |
| Credit balance                               | `credits.balance()`                                          | `credits.balance()`                                            | [Usage and credits](/concepts/credits)             |
| Webhook signature verification               | `verifyWebhook`, `WebhookSignatureError`                     | `webhooks.verify`, `WebhookSignatureError`                     | [Webhooks](/concepts/webhooks)                     |
| Rate-limit metadata                          | `parseRateLimit`, `client.lastRateLimit`                     | `parse_rate_limit`, `client.last_rate_limit`                   | [Rate limits](/concepts/rate-limits)               |
| Error links and retryability                 | `error.docUrl`, `error.retryable`                            | `error.doc_url`, `error.retryable`                             | [Retries and backoff](/concepts/retries)           |
| Test mode markers                            | `livemode`, `client.isTestMode`                              | `livemode`, `client.is_test_mode`                              | [Test mode](/getting-started/test-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](/products/availability) and the [API overview](/api-reference/overview)
before planning an integration.

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

| Version          | Where it appears             | What it tracks                                                 |
| ---------------- | ---------------------------- | -------------------------------------------------------------- |
| `/v1`            | API path                     | Wire compatibility; a breaking API change requires a new path. |
| Contract version | `info.version` in OpenAPI    | Changes to the published contract, including additive changes. |
| SDK version      | npm and PyPI package version | Changes to the SDK package surface and behavior.               |

See [Versioning](/concepts/versioning) for what may change and how you find out.