User Guide

Models, pricing, error handling, and best practices

User Guide

Looking for a quick start?

If you just want to make your first API call, see the [Quickstart guides](@/getting-started/quickstart/_index.md) — you'll be up and running in 2 minutes.

This guide covers models, pricing, error handling, and best practices for using Archipelag.io.

Prerequisites

What You Need

- An Archipelag.io account ([sign up here](https://archipelag.io/signup)) - An API key ([Settings → API Keys](https://app.archipelag.io/settings/api-keys)) - Credits in your account (new accounts include free credits)

Making Requests

{% tab(name="Python") %} ```python from archipelag import Client client = Client() # reads ARCHIPELAG_API_KEY from env # Simple chat result = client.chat("Explain quantum computing in simple terms") print(result.content) # Streaming for event in client.chat_stream("Explain quantum computing in simple terms"): if event.type == "token": print(event.content, end="", flush=True) ```

```javascript import { Archipelag } from "@archipelag/sdk"; const client = new Archipelag(); // reads ARCHIPELAG_API_KEY from env // Simple chat const result = await client.chat("Explain quantum computing in simple terms"); console.log(result.content); // Streaming await client.chatStream("Explain quantum computing in simple terms", { onToken: (token) => process.stdout.write(token), }); ```

```bash curl -X POST https://api.archipelag.io/api/v1/chat/completions \ -H "Authorization: Bearer $ARCHIPELAG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "llm-chat", "messages": [ {"role": "user", "content": "Explain quantum computing in simple terms"} ] }' ```

{% end %}

Available Models

Language Models

Model	Context	Speed	Best For
`mistral-7b`	32K	Fast	General chat, coding
`llama-3-8b`	8K	Fast	Reasoning, analysis
`llama-3-70b`	8K	Medium	Complex tasks
`codellama-34b`	16K	Medium	Code generation

Image Models

Model	Resolution	Speed	Best For
`sdxl`	1024×1024	~10s	High quality images
`sd-turbo`	512×512	~2s	Fast iterations
`flux-schnell`	1024×1024	~5s	Photorealistic

Image Generation Example

# Generate an image
response = client.images.generate(
    model="sdxl",
    prompt="A serene Japanese garden with cherry blossoms, digital art style",
    negative_prompt="blurry, low quality",
    size="1024x1024",
    steps=30
)

# Save the image
response.save("garden.png")

# Or get base64 data
image_data = response.b64_json

Understanding Pricing

Pay Only for What You Use

Archipelag.io uses a credit system with transparent per-token and per-image pricing.

Token Pricing

Model	Input (per 1K tokens)	Output (per 1K tokens)
mistral-7b	$0.0001	$0.0002
llama-3-8b	$0.0001	$0.0002
llama-3-70b	$0.0008	$0.0012

Image Pricing

Model	Per Image
sdxl	$0.01
sd-turbo	$0.003
flux-schnell	$0.008

Error Handling

{% tab(name="Python") %} ```python from archipelag import Client, APIError, RateLimitError client = Client() try: result = client.chat("Hello") except RateLimitError: print("Rate limited. Please wait and retry.") except APIError as e: print(f"API error: {e.message}") ```

```javascript import { Archipelag, APIError, RateLimitError } from "@archipelag/sdk"; const client = new Archipelag(); try { const result = await client.chat("Hello"); } catch (error) { if (error instanceof RateLimitError) { console.log("Rate limited. Please wait and retry."); } else if (error instanceof APIError) { console.log(`API error: ${error.message}`); } } ```

{% end %}

Best Practices

Optimize Your Usage

1. **Use streaming** for better user experience with LLMs 2. **Set appropriate timeouts** based on expected response length 3. **Cache responses** when the same input is used repeatedly 4. **Monitor your usage** in the dashboard to avoid surprises

Next Steps

{% card(title="API Reference", href="/api/") %} Complete API documentation with all endpoints and parameters.

SDK Guides

In-depth guides for common use cases and integrations.

Pricing Details

Full pricing information and credit packages.

{% end %}