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

# 常见问题

> Sora 2 API 使用中的常见问题解答

## 视频生成相关

如何控制视频的横屏还是竖屏？

**通过模型名控制**，而不是参数。

* **竖屏：** `sora_video2`
* **横屏：** `sora_video2-landscape`

示例：

```
# 竖屏视频
model = "sora_video2"

# 横屏视频
model = "sora_video2-landscape"
```

详见 [模型与定价](/api-capabilities/sora2/models-pricing) 页面。

生成的视频有水印吗？

**默认无水印，可选带水印（10/18 新增）**

* **默认情况：** 生成的视频**无水印**
* **带水印选项：** 在 URL 添加 `?watermark=true` 生成带 Sora 原生水印的视频

**无水印示例：**

```
https://api.yelinai.com/v1/chat/completions
```

**带水印示例：**

```
https://api.yelinai.com/v1/chat/completions?watermark=true
```

官网生成的视频仍然带有 Sora 水印。选择 YeLIn AI 可以自由选择是否需要水印！

### 为什么生成人物视频失败？

**限制原因：**

1. **真实人脸参考图会被拒绝** - 不支持上传真人照片
2. **仅支持授权真人** - 通过 `@ID` 方式使用

**可用的授权真人：**

* `@sama` - OpenAI CEO Sam Altman
* 其他已通过 Cameo 认证的用户

\*\*如何让真人出镜？\*\*需要在 Sora iOS 应用中完成 Cameo 认证：

1. 使用美区 Apple ID 下载 Sora iOS 应用
2. 在应用中进入设置
3. 找到 Cameo 认证功能
4. 按照指引完成人脸认证
5. 认证后即可在提示词中使用 `@您的ID`

**正确示例：**

```
prompt = "@sama 在长城上开心地说话"  # ✓ 可以
```

**错误示例：**

```
# ✗ 不可以 - 上传真人照片会被拒绝
# 上传了一张真人照片 + 提示词
```

未经 Cameo 认证的真人照片会被 OpenAI 拒绝，这是平台政策，非 API 限制。

生成时间太长怎么办？

**正常生成时间：**

* 排队：视高峰期而定
* 生成：2-3 分钟
* 总计：2.5-4 分钟

**优化建议：**

1. **设置合理超时：** 建议 5 分钟（300秒）

```
import httpx

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.yelinai.com/v1",
    http_client=httpx.Client(timeout=300.0)
)
```

2. **使用流式输出：** 实时查看进度

```
response = client.chat.completions.create(
    model="sora_video2",
    messages=[...],
    stream=True  # 启用流式输出
)
```

3. **避开高峰期：** 选择使用人数较少的时段

报错：We're under heavy load, please try again later

**原因：** OpenAI 官方负载过高**解决方案：**

1. 等待几分钟后重试
2. 添加重试逻辑

```
import time

max_retries = 3
for i in range(max_retries):
    try:
        response = client.chat.completions.create(...)
        break
    except Exception as e:
        if "heavy load" in str(e) and i < max_retries - 1:
            print(f"服务繁忙，{30}秒后重试...")
            time.sleep(30)
        else:
            raise
```

## API 调用相关

需要什么计费模式？

**必需设置：**令牌需要设置为**按量优先**或**按次计费**模式。**配置步骤：**

1. 登录 [YeLIn AI 控制台](https://api.yelinai.com)
2. 进入 API 管理
3. 编辑令牌设置
4. 选择”按量优先”或”按次计费”

<Note>
  请在 **Console** 查看对应界面截图。
</Note>

如果未正确设置计费模式，调用会失败。

如何查看生成进度？

**使用流式输出：**

```
stream = client.chat.completions.create(
    model="sora_video2",
    messages=[...],
    stream=True  # 启用流式输出
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end='', flush=True)
```

**进度信息示例：**

```
> ⌛️ 任务正在队列中，请耐心等待...

> 🏃 进度：36.0%

> 🏃 进度：68.5%

> ✅ 视频生成成功，[点击这里](https://xxx.mp4) 查看视频~~~
```

如何处理超时错误？

**增加超时时间：**

```
import httpx
import openai

# 设置 5 分钟超时
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.yelinai.com/v1",
    http_client=httpx.Client(timeout=300.0)
)
```

**建议超时时间：**

* 最小：5 分钟（300秒）
* 推荐：10 分钟（600秒）

支持哪些图片格式？

**图生视频支持：**

1. **URL 图片**

```
{
    "type": "image_url",
    "image_url": {
        "url": "https://example.com/image.png"
    }
}
```

2. **Base64 编码**

```
{
    "type": "image_url",
    "image_url": {
        "url": "data:image/png;base64,iVBORw0KG..."
    }
}
```

**支持的格式：**

* PNG
* JPEG/JPG
* WebP
* GIF（会使用第一帧）

**限制：**

* 最多 1 张图片
* 建议分辨率不超过 2048×2048

## 视频下载相关

视频链接有效期多久？

**有效期：仅 1 天**

视频存储在国内 CDN，**存储时效仅 1 天**。请在生成后**立即下载**保存到本地！

**最佳实践：**

```
import requests

def download_video(url, save_path):
    """下载视频到本地"""
    response = requests.get(url, stream=True)
    with open(save_path, 'wb') as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)
    print(f"已保存：{save_path}")

# 生成后立即下载
video_url = extract_video_url(result)
download_video(video_url, "my_video.mp4")
```

如何提取视频链接？

**从响应中提取：**

```
import re

def extract_video_url(content):
    """从响应内容中提取视频链接"""
    match = re.search(r'https://[^\s\)]+\.mp4', content)
    return match.group(0) if match else None

# 使用示例
response = client.chat.completions.create(...)
content = response.choices[0].message.content
video_url = extract_video_url(content)
```

**链接格式示例：**

```
https://sora.gptkey.asia/assets/sora/xxx.mp4
```

下载速度慢怎么办？

**优化建议：**

1. **使用国内网络** - 视频存储在国内 CDN，国内访问快
2. **流式下载** - 避免一次性加载到内存

```
import requests

response = requests.get(video_url, stream=True)
with open('video.mp4', 'wb') as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)
```

3. **断点续传** - 使用支持断点续传的下载工具

## 计费相关

如何计费？失败会扣费吗？

**计费方式：** 按次计费**同步API计费规则**（/v1/chat/completions）：

* ✓ 视频**成功生成**时收费
* ⚠️ **内容违规也会扣费** - 因为请求已成功（HTTP 200），平台已消耗资源
* ✗ 网络错误、连接超时**不计费**

**异步API计费规则**（/v1/videos）- 推荐：

* ✓ 仅当 status = “completed” 时收费
* ✗ **任何失败都不扣费**：
  * 内容违规（status = “failed”） → 不扣费
  * 队列超时 → 不扣费
  * 生成失败 → 不扣费

**价格（10/20 更新）：**

* 10秒/15秒视频（竖屏/横屏）：**\$0.15/次**（统一定价）
* 高清视频（sora-2-pro）：\$0.8/次（仅支持[异步API](/api-capabilities/sora2/async-api)）

**充值优惠：**

* 单次充值 \$100，约 ¥1.0/次（基础模型）

**重大降价！** 15秒模型已从 0.25降至0.25 降至 0.25降至0.15/次，与10秒模型同价。建议优先选择15秒版本获得更好效果！

**推荐生产环境使用异步API**：失败不扣费，成本更可控，稳定性更高。查看 [异步API文档](/api-capabilities/sora2/async-api)

**关于内容违规扣费（仅同步API）：**如果提示词或图片违反 OpenAI 内容政策，同步API会返回成功（HTTP 200）但带错误信息，此时**会扣费**。原因：

* 请求已成功提交到 OpenAI 平台
* 平台已消耗资源进行内容审核
* 异步API则不会扣费（status = “failed”）

**避免违规扣费的建议：**

1. 先在 [sora.chatgpt.com](https://sora.chatgpt.com) 测试提示词和图片
2. 确认通过后再通过 API 批量生成
3. 或直接使用异步API（失败不扣费）
4. 避免使用真人照片、版权内容

官方价格对比

**YeLIn AI vs OpenAI 官方：**

| 项目  | YeLIn AI | OpenAI 官方 |
| --- | -------- | --------- |
| 邀请码 | 不需要      | 需要        |
| 价格  | \$0.15/次 | 高昂且限速     |
| 水印  | 无        | 有         |
| 访问  | 国内快速     | 需要代理      |
| 稳定性 | 高        | -         |

OpenAI 官方已推出 `sora-2` 和 `sora-2-pro` 模型，但价格高昂、有速率限制，且生成视频带水印。

如何充值获得优惠？

**充值步骤：**

1. 登录 [YeLIn AI 控制台](https://api.yelinai.com)
2. 进入充值页面
3. 单次充值 \$100 或以上

**优惠价格：**

* 10秒视频：约 ¥1.0/次

**支持支付方式：**

* 支付宝
* 微信支付

## 高级功能

支持高并发吗？

**支持！基础模型稳定性极高\*\*\*\*基础模型（sora\_video2 系列）：**

* 稳定性：⭐⭐⭐⭐⭐ 极高
* 建议并发数：30 以内
* 大量并发需求（>50）：可联系我们单独保障

**高清模型（sora-2-pro）：**

* 稳定性：⭐⭐⭐ 一般
* 仅支持异步API调用
* 不建议高并发使用

**最佳实践：**

```
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.yelinai.com/v1"
)

async def generate_video(prompt):
    response = await client.chat.completions.create(
        model="sora_video2",
        messages=[{"role": "user", "content": [{"type": "text", "text": prompt}]}]
    )
    return response

# 并发生成（建议 10-30 个）
prompts = ["提示词1", "提示词2", "提示词3", ...]
tasks = [generate_video(p) for p in prompts]
results = await asyncio.gather(*tasks)
```

**联系我们：**

* 邮箱：[threezhang.cn@gmail.com](mailto:threezhang.cn@gmail.com)
* 微信：Kikivivikids
* Telegram：[https://t.me/laozhang\_cn](https://t.me/laozhang_cn)

什么是原始错误日志？

**10/20 新增功能**当视频生成失败时，API 会返回详细的原始错误信息，帮助开发者和用户明确具体问题。**错误类型示例：**

1. **内容违规（Content Violation）**

```
{
  "error": {
    "message": "Your request was rejected due to content policy violation",
    "type": "content_violation",
    "code": "content_policy_violation"
  }
}
```

2. **服务过载（Heavy Load）**

```
{
  "error": {
    "message": "We're under heavy load, please try again later",
    "type": "server_error",
    "code": "heavy_load"
  }
}
```

3. **余额不足**

```
{
  "error": {
    "message": "Insufficient credits",
    "type": "insufficient_quota",
    "code": "insufficient_credits"
  }
}
```

**如何处理错误：**

```
try:
    response = client.chat.completions.create(...)
except Exception as e:
    error_message = str(e)
    print(f"生成失败：{error_message}")

    # 根据错误类型处理
    if "content policy" in error_message:
        print("内容违规，请调整提示词或图片")
    elif "heavy load" in error_message:
        print("服务繁忙，30秒后重试")
        time.sleep(30)
    elif "insufficient" in error_message:
        print("余额不足，请充值")
```

有疑问欢迎联系我们交流：[threezhang.cn@gmail.com](mailto:threezhang.cn@gmail.com)

## 客户端使用

Cherry Studio 如何配置？

**配置步骤：**

1. 在 Cherry Studio 中添加 YeLIn AI API 配置
   * 详见：[Cherry Studio 配置文档](/scenarios/chat/cherry-studio)
2. 启用视频功能
   * 在模型设置中找到 `sora_video2`
   * 打开视频生成开关
3. 使用
   * 文生视频：直接输入提示词
   * 图生视频：上传图片 + 提示词

支持哪些客户端？

**已测试支持：**

* **Cherry Studio** ✓ - 完整支持，推荐使用
* **ChatBox** ✓ - 支持
* **OpenWebUI** ✓ - 支持
* **ChatGPT Next Web** ✓ - 支持

**任何兼容 OpenAI API 的客户端都可以使用**配置方法：

* API 端点：`https://api.yelinai.com/v1`
* 模型：选择 `sora_video2` 系列

## 技术支持

如何获取技术支持？

**联系方式：**

1. **邮箱：** [threezhang.cn@gmail.com](mailto:threezhang.cn@gmail.com)
2. **微信：** Kikivivikids
3. **Telegram：** [https://t.me/laozhang\_cn](https://t.me/laozhang_cn)
4. **文档：** []()

**提交问题时请提供：**

* 错误信息截图
* 请求参数（隐藏 API Key）
* 问题发生时间
* 使用的模型名称

在哪里查看更新日志？

**更新记录：**

* **10/07** 新增 Python 示例代码
* **10/01** 上线 Sora 2 模型，支持文生视频和图生视频

查看完整更新：[概览页面](/api-capabilities/sora2/overview)

## 最佳实践建议

## 提示词建议

* ✓ 描述具体的场景和动作
* ✓ 包含光线、氛围、情绪等细节
* ✓ 使用授权真人 ID（如 `@sama`）
* ✗ 避免描述真实人脸
* ✗ 避免过于简短的描述

## 模型选择建议

* **推荐：** `sora_video2-15s` / `sora_video2-landscape-15s`（与10秒同价，效果更好）
* 竖屏视频：`sora_video2` 系列（手机短视频、社交媒体）
* 横屏视频：`sora_video2-landscape` 系列（宽屏展示、电脑播放）
* 高清需求：`sora-2-pro`（HD 1080P，\$0.8/次，仅支持[异步API](/api-capabilities/sora2/async-api)）
* 基础模型稳定性都极高，可放心选择

## 错误处理建议

* 设置合理超时（建议 5 分钟）
* 添加重试逻辑（最多 2-3 次）
* 使用流式输出监控进度
* 记录错误日志

## 成本优化建议

* **优先选择15秒版本**（10/20 降价后与10秒同价）
* 基础模型稳定性极高，减少重试成本
* 批量生成时控制并发数（建议30以内）
* 失败不计费，可放心重试
* 及时下载视频（存储时效 1 天）
* 先用基础模型测试，再考虑高清版

## 相关链接

## 快速开始

查看示例代码和使用方法

## 模型定价

了解详细的模型对比和价格

## 使用示例

查看各种场景的应用示例

## API 参考

查看完整的 API 文档