apply changes

Author: laisbsc

docs/gateway.md

@@ -5,7 +5,7 @@ status: new
 
 # Pydantic AI Gateway
 
-**Pydantic AI Gateway** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management, and native integration with the Pydantic stack.
+**[Pydantic AI Gateway](https://pydantic.dev/gateway)** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management, and native integration with the other tools in the [Pydantic stack](https://pydantic.dev/).
 
 !!! note "Free while in Beta"
     The Pydantic AI Gateway is currently in Beta. You can bring your own key (BYOK) or buy inference through the Gateway (we will eat the card fee for now).
@@ -20,6 +20,7 @@ Sign up at [gateway.pydantic.dev](https://gateway.pydantic.dev/).
 To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), some code examples on the Pydantic AI documentation include a "Via Pydantic AI Gateway" tab, alongside a "Direct to Provider API" tab with the standard Pydantic AI model string. The main difference between them is that when using Gateway, model strings use the `gateway/` prefix.
 
 ## Key features
+
 - **API key management**: access multiple LLM providers with a single Gateway key.
 - **Cost Limits**: set spending limits at project, user, and API key levels with daily, weekly, and monthly caps.
 - **BYOK and managed providers:** Bring your own API keys (BYOK) from LLM providers, or pay for inference directly through the platform.
@@ -32,7 +33,7 @@ To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev)
 ```python {title="hello_world.py"}
 from pydantic_ai import Agent
 
-agent = Agent('gateway/chat:gpt-5')
+agent = Agent('gateway/openai:gpt-5')
 
 result = agent.run_sync('Where does "hello world" come from?')
 print(result.output)
@@ -41,34 +42,42 @@ The first known use of "hello, world" was in a 1974 textbook about the C program
 """
 ```
 # Quick Start
+
 This section contains instructions on how to set up your account and run your app with Pydantic AI Gateway credentials.
 
 ## Create an account
-Using your  GitHub or Google account, sign in at https://gateway.pydantic.dev.
+
+Using your  GitHub or Google account, sign in at [gateway.pydantic.dev](https://gateway.pydantic.dev).
 Choose a name for your organization (or accept the default). You will automatically be assigned the Admin role.
 
 A default project will be created for you. You can choose to use it, or create a new one on the [Projects](https://gateway.pydantic.dev/admin/projects) page.
 
-## Add **Providers** by bringing your own API keys (BYOK)
-Pydantic AI Gateway allows you to bring your API keys from your favourite provider(s).
+## Add **Providers**
+There are two ways to use Providers in the Pydantic AI Gateway: you can bring your own key (BYOK) or buy inference through the platform.
+
+### Bringing your own API key (BYOK)
 
 On the [Providers](https://gateway.pydantic.dev/admin/providers) page, fill in the form to add a provider. Paste your API key into the form under Credentials, and make sure to **select the Project that will be associated to this provider**. It is possible to add multiple keys from the same provider.
 
+### Use Built-in Providers
+On the top of the dashboard page, click in the 'Add billing details' button, and put in your credit card details to enable the built-in providers. This will allow you to buy inference through the available providers.
+
 ## Grant access to your team
 On the [Users](https://gateway.pydantic.dev/admin/users) page, create an invitation and share the URL with your team to allow them to access the project.
 
-## Create gateway project keys
+## Create Gateway project keys
 On the Keys page, Admins can create project keys which are not affected by spending limits. Users can only create personal keys, that will inherit spending caps from both User and Project levels, whichever is more restrictive.
 
 # Usage
 After setting up your account with the instructions above, you will be able to make an AI model request with the Pydantic AI Gateway.
 The code snippets below show how you can use PAIG with different frameworks and SDKs.
+You can add `gateway/` as prefix on every known provider that
 
-To use different models, change the model string `gateway/<api_type>:<model_name>` to other models offered by the supported providers.
+To use different models, change the model string `gateway/<api_format>:<model_name>` to other models offered by the supported providers.
 
 Examples of providers and models that can be used are:
 
-| **Provider** | **API Type**    | **Example Model**                        |
+| **Provider** | **API Format**  | **Example Model**                        |
 | --- |-----------------|------------------------------------------|
 | OpenAI | `openai`        | `gateway/openai:gpt-5`                   |
 | Anthropic | `anthropic`     | `gateway/anthropic:claude-sonnet-4-5`    |
@@ -77,7 +86,7 @@ Examples of providers and models that can be used are:
 | AWS Bedrock | `bedrock`       | `gateway/bedrock:amazon.nova-micro-v1:0` |
 
 ## Pydantic AI
-Before you start, update to the latest version of `pydantic-ai`:
+Before you start, make sure you are on version 1.16 or later of `pydantic-ai`. To update to the latest version run:
 
 === "uv"
 
@@ -91,7 +100,7 @@ Before you start, update to the latest version of `pydantic-ai`:
     pip install -U pydantic-ai
     ```
 
-Set the `PYDANTIC_AI_GATEWAY_API_KEY`  environment variable to your gateway API key:
+Set the `PYDANTIC_AI_GATEWAY_API_KEY`  environment variable to your Gateway API key:
 
 ```bash
 export PYDANTIC_AI_GATEWAY_API_KEY="YOUR_PAIG_TOKEN"
@@ -128,38 +137,39 @@ Launch Claude Code by typing `claude`. All requests will now route through the P
 
 ## SDKs
 
-=== "OpenAI SDK"
+### OpenAI SDK
 
-    ```python {title="openai_sdk.py" test="skip"}
-    import openai
+```python {title="openai_sdk.py" test="skip"}
+import openai
 
-    client = openai.Client(
-        base_url='https://gateway.pydantic.dev/proxy/chat/',
-        api_key='paig_...',
-    )
+client = openai.Client(
+    base_url='https://gateway.pydantic.dev/proxy/chat/',
+    api_key='paig_...',
+)
 
-    response = client.chat.completions.create(
-        model='gpt-5',
-        messages=[{'role': 'user', 'content': 'Hello world'}],
-    )
-    print(response.choices[0].message.content)
-    #> Hello user
-    ```
-=== "Anthropic SDK"
-
-    ```python {title="anthropic_sdk.py" test="skip"}
-    import anthropic
-
-    client = anthropic.Anthropic(
-        base_url='https://gateway.pydantic.dev/proxy/anthropic/',
-        auth_token='paig_...',
-    )
-
-    response = client.messages.create(
-        max_tokens=1000,
-        model='claude-sonnet-4-5',
-        messages=[{'role': 'user', 'content': 'Hello world'}],
-    )
-    print(response.content[0].text)
-    #> Hello user
-    ```
+response = client.chat.completions.create(
+    model='gpt-5',
+    messages=[{'role': 'user', 'content': 'Hello world'}],
+)
+print(response.choices[0].message.content)
+#> Hello user
+```
+
+### Anthropic SDK
+
+```python {title="anthropic_sdk.py" test="skip"}
+import anthropic
+
+client = anthropic.Anthropic(
+    base_url='https://gateway.pydantic.dev/proxy/anthropic/',
+    auth_token='paig_...',
+)
+
+response = client.messages.create(
+    max_tokens=1000,
+    model='claude-sonnet-4-5',
+    messages=[{'role': 'user', 'content': 'Hello world'}],
+)
+print(response.content[0].text)
+#> Hello user
+```