> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Python

> Set up a Python environment and send a complete Mk1.5 image request.

Use the Perceptron Python SDK to send image, video, and audio messages to the hosted API. These guides use SDK 0.4.0 or later. You do not need a local GPU.

## Set up your environment

Create a virtual environment, activate it, and install the client:

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade "perceptron>=0.4.0"
export PERCEPTRON_API_KEY="your-api-key"
```

On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1` and set the key with `$env:PERCEPTRON_API_KEY="your-api-key"`. See [Authentication](/perceptron-mk1.5/guides/python/auth) for key configuration and troubleshooting.

## Send an image request

Save this as `first_request.py`. It uses a public sample image and checks that the model finished its answer before printing it:

```python theme={null}
import os

from perceptron import Client, image

client = Client(
    api_key=os.environ["PERCEPTRON_API_KEY"],
    provider="perceptron",
    timeout=60.0,
)
response = client.chat.completions.create(
    model="perceptron-mk1.5",
    messages=[{
        "role": "user",
        "content": [
            image(
                "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/"
                "main/cookbook/_shared/assets/capabilities/qna/studio_scene.webp"
            ),
            {"type": "text", "text": "Describe this coastal scene and the visible objects."},
        ],
    }],
    max_completion_tokens=1024,
)

choice = response.choices[0]
if choice.finish_reason != "stop" or choice.message.tool_calls:
    raise RuntimeError(f"No completed text answer: {choice.finish_reason}")
print(choice.message.content or "")
if response.usage is not None:
    print(response.usage.to_dict())
```

Run it from the same terminal:

```bash theme={null}
python first_request.py
```

With `provider="perceptron"`, the SDK uses `https://api.perceptron.inc/v1` unless you configure a different `base_url`. It can read `PERCEPTRON_API_KEY` automatically; the example passes the key explicitly. Requests are not retried automatically. Use the bounded retry example in [Error messages](/perceptron-mk1.5/guides/error-messages) when adding retries to your application.

## Use a task helper

For a single question, `question()` builds the messages for you. Use `image()`, `video()`, or `audio()` to identify the media type:

```python theme={null}
from perceptron import image, question

result = question(
    image(
        "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/"
        "main/cookbook/_shared/assets/capabilities/qna/studio_scene.webp"
    ),
    "Describe this coastal scene and the visible objects.",
    provider="perceptron",
    model="perceptron-mk1.5",
    max_tokens=1024,
)
if not result.complete or result.finish_reason != "stop" or result.tool_calls:
    raise RuntimeError("No completed text answer")
print(result.text)
```

The helper returns a `PerceiveResult`; the message API returns a `ChatCompletion`. Both expose text, reasoning, tool calls, completion status, and asset resolution. The message API exposes typed `Usage` through `response.usage`; task helpers expose usage as a dictionary through `result.usage`. Use the message API when you need explicit conversation history or a [tool loop](/perceptron-mk1.5/guides/tool-calling).

## Build on the example

* [Request basics](/perceptron-mk1.5/guides/python/request-basics): reusable functions, message roles, and follow-up questions.
* [Files](/perceptron-mk1.5/guides/files): upload local media and reuse its file ID.
* [Multiple assets](/perceptron-mk1.5/guides/multiple-assets): include several images or videos and interpret `asset_idx`.
* [Structured outputs](/perceptron-mk1.5/capabilities/structured-outputs): validate a JSON result.
* [Tool calling](/perceptron-mk1.5/guides/tool-calling): execute application functions and return their results.
* [Python FAQs](/perceptron-mk1.5/guides/python/faqs): async requests, annotations, streaming, and common setup problems.