> ## 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.

# AI

> Go SDK の c.AI.Chat で Square Cloud AI Gateway を呼び出します。OpenAI 互換のチャット補完で、ストリーミングには対応していません。

`c.AI.Chat(ctx, request)` は、**OpenAI 互換**のチャット補完 endpoint である [AI Gateway](/en/api-reference/ai-gateway) を呼び出します。`ai:chat` スコープと Standard 以上のプランが必要です。

```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)
}
```

## リクエスト

`squarecloud.ChatRequest` のフィールドと、その JSON 名:

| フィールド                                            | 説明                                                                                                                                                                          |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Model` (`model`)                                | `cubic`。互換性のために受け付けられますが、ほかのモデルはありません。`""` は送信されません                                                                                                                         |
| `Messages` (`messages`)                          | `Role`、`Content`、`ToolCallID` (`tool_call_id`)、`ToolCalls` (`tool_calls`) を持つ `[]ChatMessage`。`Role` は `system`、`user`、`assistant` または `tool`。`Content` は `""` も含めて常に送信されます |
| `Tools` / `ToolChoice` (`tools` / `tool_choice`) | OpenAI の function calling: `Tools` は `[]json.RawMessage`、`ToolChoice` は JSON エンコード可能な任意の値                                                                                   |
| `MaxTokens` (`max_tokens`)                       | 回答の最大トークン数。`0` は送信されません                                                                                                                                                     |
| `Temperature` (`temperature`)                    | サンプリング温度。`*float64` で、`nil` は送信されません                                                                                                                                        |

レスポンスは OpenAI の形式の `ChatCompletion` です: `ID`、`Object`、`Created`、`Model`、`Choices` (`Index`、`Message`、`FinishReason`)、`Usage` (`PromptTokens`、`CompletionTokens`、`TotalTokens`)。

## ストリーミングなし

`AI.Chat` はストリーミングしません。補完全体を返します。`ChatRequest` には `stream` フィールドがなく、API は `stream: true` に対して 400 `stream_not_supported` を返します。

## タイムアウト

ゲートウェイは各リクエストに合計 **90 秒**を与え、それを過ぎると 503 `server_overloaded` を返します。`ctx` に期限がない場合、SDK はタイムアウトまで最低 2 分待機するため、ゲートウェイからの応答を受け取れます。

## エラー

AI のエラーは OpenAI の形式を使うため、コードは**小文字**です。それでも [`*APIError`](/ja/sdks/go/errors) として返され、`Code` には OpenAI のコード (コードがない場合はその `type`) が設定されます:

```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
}
```

| ステータス | コード                                                                                                     | 発生条件                              |
| ----- | ------------------------------------------------------------------------------------------------------- | --------------------------------- |
| 400   | `stream_not_supported`                                                                                  | `stream: true` が送信された             |
| 400   | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | フィールドの形式が正しくない                    |
| 400   | `context_length_exceeded`                                                                               | 会話がプランのコンテキストウィンドウを超えている          |
| 401   | `access_denied`                                                                                         | 無効な API キー                        |
| 403   | `upgrade_required`                                                                                      | プランで AI Gateway を利用できない           |
| 429   | `rate_limit_exceeded`, `concurrent_limit_reached`                                                       | リクエストが速すぎる、またはすでにリクエストが処理中        |
| 429   | `daily_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached`                       | 1 日あたりの上限を使い切った (00:00 UTC にリセット) |
| 503   | `server_overloaded`                                                                                     | 容量が満杯、または 90 秒の期限を過ぎた。安全にリトライできます |
| 503   | `daily_capacity_reached`                                                                                | プラットフォームの 1 日あたりの容量を使い切った         |

AI のエラーは、非冪等な `POST` リクエストであるため、SDK が**リトライすることはありません**。プランの上限については [AI Gateway リファレンス](/en/api-reference/ai-gateway)を参照してください。