# Terra API Documentation

> Terra 对话补全接口。支持纯文本与图片提问，同步返回 choices / usage。按次计费。

## Overview

This document describes how to call the **Terra** API.

- **Model / path slug**: `chat/terra`
- **Task type**: `sync` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/54`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `GET|POST https://apis.xiaobao.ink/api/chat/terra`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `GET / POST`
- **Note**: This endpoint accepts both GET query parameters and POST form/JSON body.

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `model` | No | 可选，固定 terra |
| `stream` | No | 可选，仅支持 false |
| `messages` | Yes | 必填，对话消息数组 |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
https://apis.xiaobao.ink/api/chat/terra?key=你的密钥
```

## Details

## 接口说明：

**Terra** 对话补全接口。支持纯文字对话，也支持在 messages 中传入图片 URL 进行多模态提问。

返回统一结构 `{code,msg,data}`，对话结果在 `data` 内（含 choices / usage 等字段）。

**请求方法：**推荐 `POST` + `application/json`。

**计费：**每次成功调用扣除 `5` 点（可在后台调整 consume）；失败不扣费。

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/json |

## 鉴权说明：

`key` 可放在 URL 查询参数、JSON Body，或 `Authorization: Bearer`。

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| key | 是 | string | 你的密钥 | 平台 API Key；也可放在 URL 或 Authorization Bearer |
| model | 否 | string | terra | 模型名称，本接口固定为 terra |
| stream | 否 | boolean | false | 是否流式；当前仅支持 false |
| messages | 是 | array | 见下方示例 | 对话消息列表，至少一条 |
| messages[].role | 是 | string | user | system / user / assistant / tool |
| messages[].content | 是 | string / array | 你好 | 纯文本 string，或多模态 content 数组（text + image_url） |
| temperature | 否 | number | 0.7 | 可选扩展参数 |
| max_tokens | 否 | integer | 2048 | 可选扩展参数 |

## 文字提问示例：

`{"key":"你的密钥","model":"terra","stream":false,"messages":[{"role":"user","content":"你好"}]}`
## 图片提问示例：

`{"key":"你的密钥","model":"terra","stream":false,"messages":[{"role":"user","content":[{"type":"text","text":"这张图片内容是什么"},{"type":"image_url","image_url":{"url":"https://你的域名/demo.png"}}]}]}`
## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 状态码，200 表示成功 |
| msg | string | 状态信息 |
| data | object | 补全结果 |
| data.id | string | 补全 ID |
| data.model | string | 实际模型，固定 terra |
| data.choices | array | 候选回复列表 |
| data.choices[].message.role | string | 通常为 assistant |
| data.choices[].message.content | string | 模型回复正文 |
| data.choices[].finish_reason | string | 结束原因，如 stop |
| data.usage | object | token 用量（prompt / completion / total） |
| data.power_cost | number | 本次扣除点数 |

## Response Example

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": "1-2ede12b5-77cc-48f9-b1d0-7ae35ee8d444",
        "object": "",
        "created": 1777897048,
        "model": "terra",
        "choices": [
            {
                "index": 0,
                "message": {
                    "role": "assistant",
                    "content": "你好！请问有什么我可以帮您的吗？"
                },
                "finish_reason": "stop"
            }
        ],
        "usage": {
            "prompt_tokens": 2,
            "completion_tokens": 20,
            "total_tokens": 22
        },
        "power_cost": 5
    }
}
```

## Error Codes

| HTTP / 业务码 | 说明 |
| --- | --- |
| 200 | 调用成功 |
| 400 | 参数错误、请求被拒绝或 stream 不支持 |
| 401 / 403 | 认证失败，请检查 key |
| 500 | 服务端异常 |

## Usage Flow

1. Obtain your API Key from the console
2. Call the endpoint with `key` and required parameters
3. Parse the JSON (or binary) response according to the examples above

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._