astarcloud 0.1.17

Official Python SDK for the AstarCloud API

AstarCloud SDK

Python SDK for the AstarCloud API with support for chat completions, tool calling, and audio transcription.

Installation

pip install astarcloud

Quick Start

from AstarCloud import AstarClient

client = AstarClient(api_key="sk-...")

# Basic chat completion
response = client.create.completion(
    messages=[{"role": "user", "content": "Hello!"}],
    model="gpt-4.1"
)

print(response.choices[0].message.content)

Tool Calling

The SDK supports tool calling for compatible models (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, astar-gpt-4.1).

Basic Tool Usage

from AstarCloud import AstarClient, ToolSpec

client = AstarClient(api_key="sk-...")

# Define a tool
weather_tool = ToolSpec(
    function={
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    }
)

# Use the tool in a completion
response = client.create.completion(
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    model="gpt-4.1",
    tools=[weather_tool],
    tool_choice="auto"
)

# Check if the model wants to call a tool
if response.choices[0].tool_calls:
    tool_call = response.choices[0].tool_calls[0]
    print(f"Tool called: {tool_call.function['name']}")
    print(f"Arguments: {tool_call.function['arguments']}")

Bound Tools Client

For convenience, you can create a client with pre-bound tools:

# Create a client with bound tools
bound_client = client.bind_tools([weather_tool])

# All completions will automatically include the bound tools
response = bound_client.create.completion(
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    model="gpt-4.1"
)

Streaming

The SDK supports streaming responses:

for chunk in client.create.completion(
    messages=[{"role": "user", "content": "Write a story"}],
    model="gpt-4.1",
    stream=True
):
    if chunk.choices[0].message.content:
        print(chunk.choices[0].message.content, end="")

Audio Transcription

The SDK supports audio transcription with various output formats:

Basic Transcription

# Transcribe an audio file
transcription = client.audio.transcribe(
    file_path="path/to/audio.mp3"
)

print(transcription.text)
print(f"Language: {transcription.language}")
print(f"Duration: {transcription.duration} seconds")

Advanced Options

# Transcribe with custom options
transcription = client.audio.transcribe(
    file_path="meeting.wav",
    model="gpt-4o-transcribe",  # or "whisper-1", "gpt-4o-mini-transcribe"
    prompt="This is a technical meeting about AI",
    temperature=0.2,
    response_format="verbose_json"  # Get detailed word-level timestamps
)

# Access segments and words (in verbose_json format)
for segment in transcription.segments:
    print(f"{segment.start}s - {segment.end}s: {segment.text}")

for word in transcription.words:
    print(f"{word.word} ({word.confidence:.2f})")

Output Formats

# Plain text output
text = client.audio.transcribe(
    file_path="audio.mp3",
    response_format="text"  # Returns string directly
)

# SRT subtitles
srt_content = client.audio.transcribe(
    file_path="video_audio.mp3",
    response_format="srt"
)

# WebVTT subtitles
vtt_content = client.audio.transcribe(
    file_path="video_audio.mp3",
    response_format="vtt"
)

Supported Audio Formats

• MP3, MP4, MPEG, MPGA, M4A, WAV, WEBM
• Maximum file size: 25MB

Available Transcription Models

• whisper-1: Standard Whisper model
• gpt-4o-transcribe: Latest GPT-4o transcription
• gpt-4o-mini-transcribe: Faster, cheaper option

Error Handling

from AstarCloud import AstarClient
from AstarCloud._exceptions import APIError, AuthenticationError

try:
    response = client.create.completion(
        messages=[{"role": "user", "content": "Hello"}],
        model="gpt-4.1"
    )
except AuthenticationError:
    print("Invalid API key")
except APIError as e:
    print(f"API error: {e}")

Model Support

Tool-Compatible Models

• gpt-4.1
• gpt-4.1-mini
• gpt-4.1-nano
• astar-gpt-4.1

Other models can be used for basic completions but do not support tool calling.