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

# SDK Go: chat do AI Gateway

> Chame o AI Gateway da Square Cloud pelo SDK Go (sdk-api-go) com c.AI.Chat: chat completions compatíveis com OpenAI, sem streaming, direto do seu código Go.

`c.AI.Chat(ctx, request)` chama o [AI Gateway](/pt-br/api-reference/ai-gateway), um endpoint de chat completions **compatível com OpenAI**. Requer o escopo `ai:chat` e um plano Standard ou superior.

Os trechos mais curtos abaixo rodam dentro do programa de [Executando os exemplos](/pt-br/sdks/go/client#executando-os-exemplos): cole um de cada vez em `main` e execute o `goimports`.

```go theme={"system"}
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

func main() {
	ctx := context.Background()
	c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))

	completion, err := c.AI.Chat(ctx, squarecloud.ChatRequest{
		Model: "cubic",
		Messages: []squarecloud.ChatMessage{
			{Role: "system", Content: "You are a helpful assistant."},
			{Role: "user", Content: "What is Square Cloud?"},
		},
		MaxTokens: 512,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
	fmt.Println(completion.Usage.TotalTokens)
}
```

## Requisição

Campos de `squarecloud.ChatRequest`, com seus nomes em JSON:

| Campo | Descrição |
| - | - |
| `Model` (`model`) | `cubic`. Aceito por compatibilidade: não existe outro modelo. `""` não é enviado |
| `Messages` (`messages`) | `[]ChatMessage` com `Role`, `Content`, `ToolCallID` (`tool_call_id`) e `ToolCalls` (`tool_calls`). `Role` é `system`, `user`, `assistant` ou `tool`. `Content` é sempre enviado, `""` incluído |
| `Tools` / `ToolChoice` (`tools` / `tool_choice`) | Function calling da OpenAI: `Tools` é um `[]json.RawMessage`, `ToolChoice` qualquer valor codificável em JSON |
| `MaxTokens` (`max_tokens`) | Máximo de tokens da resposta. `0` não é enviado |
| `Temperature` (`temperature`) | Temperatura de amostragem, um `*float64`. `nil` não é enviado |

A resposta é um `ChatCompletion` no formato da OpenAI: `ID`, `Object`, `Created`, `Model`, `Choices` (`Index`, `Message`, `FinishReason`) e `Usage` (`PromptTokens`, `CompletionTokens`, `TotalTokens`).

## Sem streaming

`AI.Chat` não faz streaming: ele retorna a completion inteira. `ChatRequest` não tem campo `stream`; a API responde 400 `stream_not_supported` a `stream: true`.

## Timeout

O gateway dá a cada requisição **90 segundos** no total e então responde 503 `server_overloaded`. Sem um prazo no `ctx`, o SDK espera pelo menos 2 minutos antes de expirar, então você recebe a resposta do gateway.

## Erros

Os erros de IA usam o formato da OpenAI, então seus códigos são em **minúsculas**. Eles ainda são retornados como um [`*APIError`](/pt-br/sdks/go/errors), com `Code` definido como o código da OpenAI (ou seu `type` quando não há código):

```go theme={"system"}
_, err := c.AI.Chat(ctx, squarecloud.ChatRequest{
	Messages: []squarecloud.ChatMessage{{Role: "user", Content: "Hi"}},
})

var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.Code == "server_overloaded" {
	// safe to retry yourself
}
```

| Status | Código | Quando |
| - | - | - |
| 400 | `stream_not_supported` | `stream: true` foi enviado |
| 400 | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | Um campo malformado |
| 400 | `context_length_exceeded` | A conversa excede a janela de contexto do plano |
| 401 | `access_denied` | Chave de API inválida |
| 403 | `upgrade_required` | O plano não tem acesso ao AI Gateway |
| 429 | `rate_limit_exceeded`, `concurrent_limit_reached` | Rápido demais, ou uma requisição já em andamento |
| 429 | `daily_limit_reached`, `weekly_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached` | Um limite diário ou semanal foi esgotado (limites diários reiniciam às 00:00 UTC, os semanais na segunda-feira às 00:00 UTC) |
| 503 | `server_overloaded` | A capacidade está cheia ou o prazo de 90 s passou: é seguro tentar novamente |
| 503 | `daily_capacity_reached` | A capacidade diária da plataforma foi esgotada |

O SDK **nunca tenta novamente** erros de IA: a requisição é um `POST` não idempotente. Veja a [referência do AI Gateway](/pt-br/api-reference/ai-gateway) para os limites dos planos.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Erros" icon="triangle-exclamation" href="/pt-br/sdks/go/errors">
    Classe de erro, novas tentativas e rate limits.
  </Card>

  <Card title="Referência do AI Gateway" icon="code" href="/pt-br/api-reference/ai-gateway">
    Modelos, limites por plano e o endpoint compatível com a OpenAI.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.