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

# 创建 Iframe 组件

> 创建一个新的可嵌入聊天组件配置，并将其关联到某个 API 密钥。

## 请求

<ParamField body="api_key_id" type="string" required>
  要关联此组件的 API 密钥 ID。该组件将使用此密钥的额度、Brand Soul 以及允许的来源域名。
</ParamField>

<ParamField body="name" type="string" optional>
  组件的显示名称。默认值：`"My Widget"`。
</ParamField>

<ParamField body="appearance" type="object" optional>
  外观自定义设置：`primaryColor`、`position`（`bottom-right` | `bottom-left`）、`borderRadius`、`fontFamily`，以及自定义 CSS 覆盖项。
</ParamField>

<ParamField body="behavior" type="object" optional>
  行为设置：`welcomeMessage`、`placeholder`、`maxPromptLength`、`enableFileUpload`、`enableVoice`、`strictAbuse`（启用限流启发式策略）。
</ParamField>

<ParamField body="security" type="object" optional>
  安全设置：`requireTurnstile`（机器人防护）、`allowedOrigins`（覆盖允许的来源域名白名单）。
</ParamField>

## 响应

<ResponseField name="id" type="string">
  组件配置的 UUID。在嵌入脚本中将其用作 `configId`。
</ResponseField>

<ResponseField name="name" type="string">
  组件的显示名称。
</ResponseField>

<ResponseField name="status" type="string">
  `"active"` 或 `"disabled"`。
</ResponseField>

<ResponseField name="embed_snippet" type="string">
  可直接使用的 HTML `<script>` 标签，用于嵌入到你的网站中。
</ResponseField>

## 身份验证

需要仪表盘会话。

## 示例

```bash curl theme={null}
curl -X POST https://www.hitheo.ai/api/v1/iframes \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key_id": "key_abc123",
    "name": "Support Widget",
    "appearance": { "primaryColor": "#715eac" },
    "behavior": { "welcomeMessage": "Hi! How can I help?", "strictAbuse": true }
  }'
```


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