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

# Introduction

# XAI (Grok) 简介

欢迎使用 **XAI** 服务文档！

本服务集成了 **xAI 的 Grok** 模型，用于 AI 驱动的图像和视频生成。使用 `grok-imagine-image` 和 `grok-imagine-video`，您可以通过文本提示创建精美的视觉内容，或使用参考图片引导生成。

## 功能特性

**XAI Grok** 提供以下生成能力：

* **文生图**：使用 **grok-imagine-image** 模型从文本提示生成高质量图像，支持自定义宽高比。
* **图生图**：提供参考图片和提示词来编辑或变换图像 — 输出尺寸跟随参考图片。
* **文生视频**：使用 **grok-imagine-video** 模型从文本提示生成视频，可控制时长（6秒/10秒/15秒）、宽高比和分辨率。
* **图生视频**：使用参考图片引导视频生成 — 提供参考图片时，宽高比和分辨率将自动跟随参考图片。
* **异步任务系统**：所有生成请求都会返回一个 `taskId`。轮询任务端点可获取状态和结果。

## 如何使用 XAI

1. **创建生成任务**：调用图像或视频生成端点，传入提示词和参数。
2. **获取任务 ID**：响应中返回用于跟踪的 `taskId`。
3. **轮询任务状态**：使用任务结果端点（`GET /xai/tasks`）检查进度。
4. **下载结果**：任务状态变为 `completed` 后，结果中包含您生成的内容。

## 可用端点

### 图像生成

| 端点            | 方法   | 描述             |
| ------------- | ---- | -------------- |
| `/xai/images` | POST | 从文本提示或参考图片生成图像 |

### 视频生成

| 端点            | 方法   | 描述             |
| ------------- | ---- | -------------- |
| `/xai/videos` | POST | 从文本提示或参考图片生成视频 |

### 任务管理

| 端点           | 方法  | 描述                  |
| ------------ | --- | ------------------- |
| `/xai/tasks` | GET | 通过 taskId 查询任务状态和结果 |

***

### 浏览 API 文档

**图像：**

* [生成图像](generate-image) — 使用 Grok 创建或编辑图像

**视频：**

* [生成视频](generate-video) — 从文本或图片创建视频

**任务：**

* [获取任务结果](task) — 检查任务状态并下载结果

***

## 关键参数

### 图像生成

| 参数            | 必填 | 描述                              |
| ------------- | -- | ------------------------------- |
| `prompt`      | 是  | 图像描述（最多 1000 个字符）               |
| `model`       | 是  | `grok-imagine-image`            |
| `aspectRatio` | 否  | `1:1`、`2:3`、`3:2`、`9:16`、`16:9` |
| `images`      | 否  | 参考图片 URL（最多 1 张）；提供时，输出尺寸跟随参考图片 |

### 视频生成

| 参数            | 必填 | 描述                                                 |
| ------------- | -- | -------------------------------------------------- |
| `prompt`      | 是  | 视频描述（最多 1000 个字符）                                  |
| `model`       | 是  | `grok-imagine-video`                               |
| `duration`    | 否  | `6`（默认）、`10` 或 `15` 秒                              |
| `aspectRatio` | 否  | `1:1`、`2:3`、`3:2`、`9:16`、`16:9`                    |
| `resolution`  | 否  | `480P`、`720P`（默认）                                  |
| `images`      | 否  | 参考图片 URL（最多 1 张）；提供时，aspectRatio 和 resolution 将被忽略 |

### 任务状态值

| 状态           | 描述          |
| ------------ | ----------- |
| `pending`    | 任务排队中       |
| `ready`      | 任务准备就绪，等待处理 |
| `assigned`   | 任务已分配给工作节点  |
| `processing` | 任务正在处理中     |
| `completed`  | 任务成功完成      |
| `failed`     | 任务遇到错误      |
| `cancelled`  | 任务已取消       |
| `timeout`    | 任务超时        |

## 最佳实践

1. **编写清晰的提示词**：具体而详细的描述可获得更准确的结果。
2. **使用参考图片**：如有可用的参考图片，可提供它以更精确地控制风格和构图。
3. **选择合适的设置**：根据使用场景选择合适的宽高比、时长和分辨率。
4. **实现轮询机制**：轮询任务状态时使用指数退避策略以避免频率限制。
5. **优雅地处理错误**：检查 `failed` 和 `timeout` 状态，使用 `errorMessage` / `errorCode` 进行诊断。