Skip to main content
Use this recipe to get your first Phaseo integration running without picking a paid model yet. Instead of picking one free model yourself, send requests to phaseo/free. Phaseo will choose an available free model that supports the request you are making.

​
When to use this

  • You want a working prototype before choosing a paid model.
  • You expect the best free option to change over time.
  • You want one stable model ID in application code while Phaseo handles free-provider changes behind the scenes.

​
Example request

curl https://api.phaseo.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "phaseo/free",
    "input": "Summarize why provider-aware free routing helps prototypes.",
    "temperature": 0.2
  }'

import Phaseo from "@phaseo/sdk";

const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });

const response = await client.generateResponse({
  model: "phaseo/free",
  input: "Summarize why provider-aware free routing helps prototypes.",
  temperature: 0.2,
});

console.log(response.output_text);

from phaseo import Phaseo

client = Phaseo(api_key="YOUR_API_KEY")

response = client.generate_response(
    {
        "model": "phaseo/free",
        "input": "Summarize why provider-aware free routing helps prototypes.",
        "temperature": 0.2,
    }
)

print(response.get("output_text"))

package main

import (
  "context"
  "fmt"

  phaseo "github.com/phaseoteam/Phaseo/packages/sdk/sdk-go"
)

func main() {
  client := phaseo.New("YOUR_API_KEY", "https://api.phaseo.ai/v1")

  response, err := client.GenerateResponse(context.Background(), phaseo.ResponsesRequest{
    Model: "phaseo/free",
    Input: map[string]interface{}{
      "role": "user",
      "content": []map[string]string{
        {
          "type": "input_text",
          "text": "Summarize why provider-aware free routing helps prototypes.",
        },
      },
    },
  })
  if err != nil {
    panic(err)
  }

  fmt.Println(response)
}

using PhaseoSdk;
using System.Collections.Generic;

var client = new Phaseo("YOUR_API_KEY");

var response = await client.GenerateResponse(new Dictionary<string, object>
{
    ["model"] = "phaseo/free",
    ["input"] = "Summarize why provider-aware free routing helps prototypes.",
    ["temperature"] = 0.2
});

Console.WriteLine(response);

<?php
require 'vendor/autoload.php';

use Phaseo\Sdk\Phaseo;

$client = new Phaseo(getenv('PHASEO_API_KEY') ?: 'YOUR_API_KEY');

$response = $client->generateResponse([
    'model' => 'phaseo/free',
    'input' => 'Summarize why provider-aware free routing helps prototypes.',
    'temperature' => 0.2,
]);

print_r($response);

require 'phaseo_sdk'

client = PhaseoSdk::Phaseo.new(api_key: ENV.fetch('PHASEO_API_KEY', 'YOUR_API_KEY'))

response = client.generate_response(
  model: 'phaseo/free',
  input: 'Summarize why provider-aware free routing helps prototypes.',
  temperature: 0.2
)

puts response

​
What happens behind the scenes

  1. Your request goes to the shared phaseo/free alias.
  2. Phaseo checks which free models can handle that request.
  3. One available free model is selected and used for the response.
  4. Request details still show the exact model that ran, so you can inspect or debug it later.

​
After your first request

  • In Gateway -> Usage, open the request details and confirm which model was used.
  • If the request is blocked by workspace policy, check the request details to see which setting stopped it.
  • If no free model supports the feature you need, switch from phaseo/free to a specific paid model instead of retrying the same request.

​
Production notes

  • Keep phaseo/free for prototypes, demos, and low-stakes traffic.
  • If you need predictable latency, output style, or provider choice, move to a specific model once you know what works best.
  • If you need stable prompt behavior across services, pair this recipe with Presets.
Last modified on July 9, 2026