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

# Quickstart (5 minutes)

> From signup to first successful request in under 5 minutes, starting on a free model.

This guide is intentionally short. Follow it in order and you should have a working integration in a few minutes.

***

## 1. Create an API key

1. Open the [AI Stats Dashboard](https://ai-stats.phaseo.app/gateway/keys).
2. Create a key under **Gateway -> Keys**.
3. Copy it once and store it securely.

Use this format:

```http theme={null}
Authorization: Bearer aistats_v1_sk_<kid>_<secret>
```

<Danger>
  Treat your API key like a password. Do not expose it in client-side code.
</Danger>

***

## 2. Start with a free model (no deposit required)

Use `POST /v1/responses` for the fastest first success.

<Note>
  Requests to `:free` models do not require deposited credits. Paid models still require available wallet balance.
</Note>

### Request (request format)

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.phaseo.app/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google/gemma-3-27b:free",
      "input": "Reply with: quickstart works",
      "temperature": 0
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.phaseo.app/v1/responses", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "google/gemma-3-27b:free",
      input: "Reply with: quickstart works",
      temperature: 0,
    }),
  });

  const data = await response.json();
  const assistantText = data.output
    ?.find((item) => item.type === "message")
    ?.content?.find((part) => part.type === "output_text")
    ?.text;

  console.log(assistantText);
  ```

  ```typescript TypeScript SDK theme={null}
  import AIStats from "@ai-stats/sdk";

  const client = new AIStats({ apiKey: process.env.AI_STATS_API_KEY! });

  const response = await client.generateResponse({
    model: "google/gemma-3-27b:free",
    input: "Reply with: quickstart works",
    temperature: 0,
  });

  const assistantText = response.output
    ?.find((item: any) => item.type === "message")
    ?.content?.find((part: any) => part.type === "output_text")
    ?.text;

  console.log(assistantText);
  ```

  ```python Python SDK theme={null}
  from ai_stats import AIStats

  client = AIStats(api_key="YOUR_API_KEY")

  response = client.generate_response(
      {
          "model": "google/gemma-3-27b:free",
          "input": "Reply with: quickstart works",
          "temperature": 0,
      }
  )

  assistant_text = next(
      (
          part.get("text")
          for item in response.get("output", [])
          if item.get("type") == "message"
          for part in item.get("content", [])
          if part.get("type") == "output_text"
      ),
      None,
  )

  print(assistant_text)
  ```

  ```typescript Vercel AI SDK theme={null}
  import { aiStats } from "@ai-stats/ai-sdk-provider";
  import { generateText } from "ai";

  const result = await generateText({
    model: aiStats("google/gemma-3-27b:free"),
    prompt: "Reply with: quickstart works",
  });

  console.log(result.text);
  ```
</CodeGroup>

### Response (response format)

```json theme={null}
{
  "id": "resp_...",
  "object": "response",
  "created_at": 1730000000,
  "status": "completed",
  "completed_at": 1730000001,
  "model": "google/gemma-3-27b:free",
  "output": [
    {
      "type": "message",
      "id": "msg_...",
      "status": "completed",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "quickstart works", "annotations": [] }]
    }
  ],
  "usage": {
    "input_tokens": 9,
    "output_tokens": 3,
    "total_tokens": 12
  },
  "error": null,
  "incomplete_details": null
}
```

For Responses API calls, read assistant text from `output[].content[]` where `type` is `output_text`.\
For Vercel AI SDK calls, use `result.text`.

***

## 3. If it fails, check these first

* `401`: key format or header issue.
* `400`: request body shape or unsupported parameter.
* `402`: paid model without sufficient balance. Use a `:free` model or top up credits.
* `429/5xx`: retry with backoff.

Use the [Error Handling reference](./api-reference/errors.mdx) to debug quickly.

***

## 4. Video jobs are asynchronous

Video creation is long-running by design.

1. Create a job with `POST /v1/videos`.
2. Poll status with `GET /v1/videos/{video_id}` until completed.
3. Download content from `GET /v1/videos/{video_id}/content`.

```bash theme={null}
# Create
curl https://api.phaseo.app/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<video-model-id>",
    "prompt": "A cinematic sunrise over a mountain lake"
  }'

# Poll status
curl https://api.phaseo.app/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## 5. Next steps

<Columns cols={2}>
  <Card title="Integrating with the Gateway" icon="plug" href="./developers/integrating-with-the-gateway.mdx">
    Production integration patterns and endpoint selection.
  </Card>

  <Card title="API Reference" icon="book" href="./api-reference/introduction.mdx">
    Full request and response docs for every endpoint.
  </Card>

  <Card title="Examples" icon="code" href="./guides/examples.mdx">
    More complete request samples for common workflows.
  </Card>

  <Card title="Support" icon="message-circle" href="./community/contact-and-support.mdx">
    Get help with debugging, routing, and model behavior.
  </Card>
</Columns>