Official JavaScript and Python SDKs

Use small dependency-free clients with types generated from the deployed OpenAPI contract.

JavaScript / TypeScript

Requires Node.js 22+ or a compatible server-side fetch runtime. Install the official downloadable npm archive:

npm install https://metaphrase.msalman.com/downloads/metaphrase-sdk-1.0.0.tgz

Save as example.mjs, set METAPHRASE_API_KEY, then run node example.mjs:

import {MetaPhrase,MetaPhraseError} from '@metaphrase/sdk';
const client=new MetaPhrase({api_key:process.env.METAPHRASE_API_KEY});
try{
  const response=await client.grammar({text:'The best ideas deserves to be shared.',language:'en-US'});
  console.log(response.result.text,response.usage);
}catch(error){
  if(error instanceof MetaPhraseError)console.error(error.status,error.code,error.message,error.docs_url);
  else throw error;
}

All methods are named paraphrase, grammar, detect, translate, summarize, and cite and accept one typed request object. They return the full typed response envelope, not just text. Constructor options use snake_case: api_key, optional base_url (origin, without /api/v1), and timeout_ms (default 250,000). A custom fetch can be provided for server runtimes/tests. Pass {signal: AbortSignal} as the second method argument to cancel.

Use client.stream('paraphrase', request) for streaming; do not pass stream:true to an ordinary JSON method. See streaming. Secret-key SDKs belong on the backend; the JavaScript client rejects browser construction.

Python

Requires Python 3.11+. Create a virtual environment and install the official wheel:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install https://metaphrase.msalman.com/downloads/metaphrase_sdk-1.0.0-py3-none-any.whl

Save as example.py, set METAPHRASE_API_KEY, then run python example.py:

import os
from metaphrase_sdk import MetaPhrase, MetaPhraseError

client = MetaPhrase(api_key=os.environ['METAPHRASE_API_KEY'])
try:
    result = client.grammar({'text': 'The best ideas deserves to be shared.', 'language': 'en-US'})
    print(result['result']['text'])
    print(result['usage'])
except MetaPhraseError as error:
    print(error.status, error.code, str(error), error.docs_url)

The import package is metaphrase_sdk (with phrase); use that exact name. Constructor options: api_key, base_url (origin), and timeout in seconds (default 250). Methods accept a typed request dictionary and return typed response dictionaries; types are exported from metaphrase_sdk.types. The Python client uses only the standard library and does not automatically retry.

For streaming:

import os
from metaphrase_sdk import MetaPhrase
client = MetaPhrase(api_key=os.environ['METAPHRASE_API_KEY'])
for event in client.stream('paraphrase', {'text': 'Good writing makes an idea easier to understand.'}):
    if event['event'] == 'delta':
        print(event['data']['text_delta'], end='', flush=True)
    elif event['event'] == 'done':
        print('\n', event['data']['usage'])

Versioning and publication

SDK 1.0.0 targets REST /api/v1. The checked-in generator reads the same OpenAPI schemas used by the API docs. Every build regenerates client types, methods, downloads, Postman and Insomnia files. Contract checks detect differences between generated artifacts and the source schemas.

The archives above work with npm and pip without a registry account. Publication under npm/PyPI package names requires the operator's registry ownership and credentials; do not assume a similarly named public package is this official SDK. Install from this domain until registry publication is verified. The package source includes publication instructions and a specification checksum.