Quickstart

Ship your first stateful AI app in 10 minutes. This guide walks you through installation, authentication, and your first API call.

# Install the PortModels SDK
pip install portmodels

# Create a client and start building
from portmodels import Client

client = Client(api_key="pm_test_your_key_here")

# Send a chat message with automatic user storage
response = client.chat.complete(
  model="gpt-4",
  messages=[{"role": "user", "content": "Hello"}],
  user_id="user_abc123",
  system_prompt="You are a helpful assistant."
)

print(response.content)

Authentication

All API requests require an API key. Get your key from the dashboard after signing up.

# Include your API key in the Authorization header
headers = {
  "Authorization": "Bearer pm_your_api_key",
  "Content-Type": "application/json"
}

Installation

Use the hosted API directly or install the SDK for your preferred runtime. Start with a single API key, then configure environments for local development and production.

# Python
pip install portmodels

# JavaScript
npm install portmodels

# Environment
export PORTMODELS_API_KEY="pm_your_api_key"

/chat — Send a Message

The core endpoint for interacting with AI models. Automatically handles user storage and credit deduction.

Request

POST /chat
{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Write a Python function"}
  ],
  "user_id": "user_abc123",
  "temperature": 0.7,
  "max_tokens": 500
}

Response

{
  "id": "chat_xyz789",
  "model": "gpt-4",
  "content": "Here is a Python function...",
  "credits_used": 42,
  "user_balance": 958
}

/storage — User Data

Store and retrieve per-user data. Automatically isolated per app and user.

Set a value

POST /storage
{
  "user_id": "user_abc123",
  "key": "preferences",
  "value": {"theme": "dark", "notifications": true}
}

Get a value

GET /storage?user_id=user_abc123&key=preferences

/models — Available Models

List available models and their credit costs.

GET /models

[
  {"id": "gpt-4", "name": "GPT-4", "credits_per_1k": 120},
  {"id": "gpt-3.5-turbo", "name": "GPT-3.5 Turbo", "credits_per_1k": 2},
  {"id": "claude-3", "name": "Claude 3", "credits_per_1k": 80}
]

/payouts — Revenue & Withdrawals

Track your revenue and request withdrawals. Minimum payout is $10.

Get revenue stats

GET /payouts/stats

{
  "total_earned": 247.50,
  "pending_payout": 32.40,
  "lifetime_credits_used": 154250,
  "revenue_share": 0.90
}

System Prompt Presets

Create reusable system prompt configurations for consistent AI behavior across your apps.

# Create a system preset for your app
client.models.create_preset(
  name="helpful-coder",
  system_prompt="You are a helpful coding assistant. "
  "Always provide concise, well-commented code. "
  "Explain your reasoning briefly.",
  temperature=0.7,
  max_tokens=1000
)

User Storage Patterns

Model responses stay useful when you store lightweight, app-specific state. Keep durable user preferences, recent workflow context, and billing-safe metadata in separate keys so retrieval stays predictable.

# Recommended storage layout
preferences/theme
preferences/notifications
sessions/current-workflow
usage/monthly-budget

Credit Optimization

Control spend by routing simple tasks to lower-cost models, caching repeated system prompts, and storing reusable context instead of re-sending the full conversation each time.

# Example policy
summaries -> low-cost model
code review -> premium model
long-lived user context -> storage key lookup

Monetization Setup

Set per-action pricing, define free trial limits, and monitor payout thresholds before opening your app to users. Keep pricing predictable so users understand exactly what each workflow costs.

# Suggested launch checklist
1. Set credits per action
2. Define monthly user caps
3. Test payout reporting
4. Publish app listing