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

# 常见问题（旧线路已过时）

> Sora 2 旧线路常见问题，仅供历史排查参考；当前请使用 Sora 官方 API 转发方案。

<Warning>
  该页面属于 Sora2 旧线路文档，目前已过时，仅供历史排查参考。当前可用入口请使用 [Sora 官方 API 转发方案](/api-capabilities/sora2/official-forward)。
</Warning>

## 视频生成相关

<AccordionGroup>
  <Accordion title="如何控制视频的横屏还是竖屏？" icon="smartphone">
    **通过模型名控制**，而不是参数。

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

    示例：

    ```python theme={null}
    # 竖屏视频
    model = "sora_video2"

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

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

  <Accordion title="生成的视频有水印吗？" icon="droplet">
    **水印策略以模型返回为准，可选带水印（10/18 新增）**

    * **默认情况：** 生成的视频**水印策略以模型返回为准**
    * **带水印选项：** 在 URL 添加 `?watermark=true` 生成带 Sora 原生水印的视频

    **水印策略以模型返回为准示例：**

    ```bash theme={null}
    https://api2.laozhang.ai/v1/chat/completions
    ```

    **带水印示例：**

    ```bash theme={null}
    https://api2.laozhang.ai/v1/chat/completions?watermark=true
    ```

    <Tip>
      官网生成的视频仍然带有 Sora 水印。选择 laozhang.ai 可以自由选择是否需要水印！
    </Tip>
  </Accordion>

  <Accordion title="为什么生成人物视频失败？" icon="user-x">
    **限制原因：**

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

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

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

    **如何让真人出镜？**

    需要在 Sora iOS 应用中完成 Cameo 认证：

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

    **正确示例：**

    ```python theme={null}
    prompt = "@sama 在长城上开心地说话"  # ✓ 可以
    ```

    **错误示例：**

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

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

  <Accordion title="生成时间太长怎么办？" icon="timer">
    **正常生成时间：**

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

    **优化建议：**

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

    ```python theme={null}
    import httpx

    client = openai.OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api2.laozhang.ai/v1",
        http_client=httpx.Client(timeout=300.0)
    )
    ```

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

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

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

  <Accordion title="报错：We're under heavy load, please try again later" icon="server">
    **原因：** OpenAI 官方负载过高

    **解决方案：**

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

    ```python theme={null}
    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
    ```
  </Accordion>
</AccordionGroup>

## API 调用相关

<AccordionGroup>
  <Accordion title="需要什么计费模式？" icon="credit-card">
    **必需设置：**

    令牌需要设置为**按量优先**或**按次计费**模式。

    **配置步骤：**

    1. 登录 [laozhang.ai 控制台](https://api2.laozhang.ai)
    2. 进入 API 管理
    3. 编辑令牌设置
    4. 选择"按量优先"或"按次计费"

    <img src="https://mintcdn.com/laozhangai-edd05f2c/_loZ0Jy0ZI__xJ9z/images/sora2-token-setting.png?fit=max&auto=format&n=_loZ0Jy0ZI__xJ9z&q=85&s=d54128f51509467d6b73d207bbe5c86f" alt="令牌设置示例" width="1280" height="537" data-path="images/sora2-token-setting.png" />

    <Warning>
      如果未正确设置计费模式，调用会失败。
    </Warning>
  </Accordion>

  <Accordion title="如何查看生成进度？" icon="loader-circle">
    **使用流式输出：**

    ```python theme={null}
    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) 查看视频~~~
    ```
  </Accordion>

  <Accordion title="如何处理超时错误？" icon="history">
    **增加超时时间：**

    ```python theme={null}
    import httpx
    import openai

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

    **建议超时时间：**

    * 最小：5 分钟（300秒）
    * 推荐：10 分钟（600秒）
  </Accordion>

  <Accordion title="支持哪些图片格式？" icon="image">
    **图生视频支持：**

    1. **URL 图片**

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

    2. **Base64 编码**

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

    **支持的格式：**

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

    **限制：**

    * 最多 1 张图片
    * 建议分辨率不超过 2048×2048
  </Accordion>
</AccordionGroup>

## 视频下载相关

<AccordionGroup>
  <Accordion title="视频链接有效期多久？" icon="unlink">
    **有效期：仅 1 天**

    <Warning>
      视频通过临时 CDN 链接返回，**存储时效仅 1 天**。请在生成后**立即下载**保存到本地！
    </Warning>

    **最佳实践：**

    ```python theme={null}
    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")
    ```
  </Accordion>

  <Accordion title="如何提取视频链接？" icon="link">
    **从响应中提取：**

    ```python theme={null}
    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
    ```
  </Accordion>

  <Accordion title="下载速度慢怎么办？" icon="gauge">
    **优化建议：**

    1. **使用稳定网络** - 下载时建议保持连接稳定
    2. **流式下载** - 避免一次性加载到内存

    ```python theme={null}
    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. **断点续传** - 使用支持断点续传的下载工具
  </Accordion>
</AccordionGroup>

## 计费相关

<AccordionGroup>
  <Accordion title="如何确认异常订单计费？" icon="dollar-sign">
    **计费方式：** 按次计费

    **计费口径：**

    * 具体扣费以控制台订单和账单记录为准
    * 内容安全、超时、取消、异常状态按控制台记录处理
    * 如订单状态异常，请联系客服复核

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

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

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

    <Tip>
      **推荐生产环境使用异步API**：失败计费以控制台记录为准，成本更可控，稳定性更高。查看 [异步API文档](/api-capabilities/sora2/async-api)
    </Tip>

    **关于内容违规扣费（仅同步API）：**

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

    * 请求已成功提交到 OpenAI 平台
    * 平台已消耗资源进行内容审核
    * 异步API则计费以控制台记录为准（status = "failed"）

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

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

  <Accordion title="外部参考价对比" icon="scale">
    **laozhang.ai vs OpenAI 官方：**

    | 项目   | laozhang.ai | OpenAI 官方 |
    | ---- | ----------- | --------- |
    | 邀请码  | 不需要         | 需要        |
    | 价格   | \$0.15/次    | 高昂且限速     |
    | 水印   | 无           | 有         |
    | 接入方式 | 统一 API 转发   | 官方 API 直连 |
    | 稳定性  | 高           | -         |

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

  <Accordion title="在哪里查看实际扣费？" icon="wallet">
    登录 [laozhang.ai 控制台](https://api2.laozhang.ai)，进入账单或调用日志页面查看。实际扣费以模型、请求结果和控制台实时价格为准。

    **支付方式：** 以控制台当前展示的可用方式为准。
  </Accordion>
</AccordionGroup>

## 高级功能

<AccordionGroup>
  <Accordion title="支持高并发吗？" icon="gauge">
    **支持！基础模型稳定性极高**

    **基础模型（sora\_video2 系列）：**

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

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

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

    **最佳实践：**

    ```python theme={null}
    import asyncio
    from openai import AsyncOpenAI

    client = AsyncOpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api2.laozhang.ai/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)
    ```

    **联系我们：**

    * 邮箱：[hi@laozhang.ai](mailto:hi@laozhang.ai)
    * Telegram：[https://t.me/laozhang\_cn](https://t.me/laozhang_cn)
  </Accordion>

  <Accordion title="什么是原始错误日志？" icon="file-text">
    **10/20 新增功能**

    当视频生成失败时，API 会返回详细的原始错误信息，帮助开发者和用户明确具体问题。

    **错误类型示例：**

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

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

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

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

    3. **余额不足**

    ```json theme={null}
    {
      "error": {
        "message": "Insufficient credits",
        "type": "insufficient_quota",
        "code": "insufficient_credits"
      }
    }
    ```

    **如何处理错误：**

    ```python theme={null}
    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("余额不足，请确认账户额度")
    ```

    <Tip>
      有疑问欢迎联系我们交流：[hi@laozhang.ai](mailto:hi@laozhang.ai)
    </Tip>
  </Accordion>
</AccordionGroup>

## 客户端使用

<AccordionGroup>
  <Accordion title="Cherry Studio 如何配置？" icon="message-circle">
    **配置步骤：**

    1. 在 Cherry Studio 中添加 laozhang.ai API 配置
       * 详见：[Cherry Studio 配置文档](https://docs.laozhang.ai/scenarios/chat/cherry-studio)

    2. 启用视频功能
       * 在模型设置中找到 `sora_video2`
       * 打开视频生成开关

    3. 使用
       * 文生视频：直接输入提示词
       * 图生视频：上传图片 + 提示词
  </Accordion>

  <Accordion title="支持哪些客户端？" icon="grid-2x2">
    **已测试支持：**

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

    **任何兼容 OpenAI API 的客户端都可以使用**

    配置方法：

    * API 端点：`https://api2.laozhang.ai/v1`
    * 模型：选择 `sora_video2` 系列
  </Accordion>
</AccordionGroup>

## 技术支持

<AccordionGroup>
  <Accordion title="如何获取技术支持？" icon="headset">
    **联系方式：**

    1. **邮箱：** [hi@laozhang.ai](mailto:hi@laozhang.ai)
    2. **Telegram：** [https://t.me/laozhang\_cn](https://t.me/laozhang_cn)
    3. **文档：** [https://docs.laozhang.ai](https://docs.laozhang.ai)

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

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

  <Accordion title="在哪里查看更新日志？" icon="history">
    **更新记录：**

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

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

## 最佳实践建议

<Card title="提示词建议" icon="lightbulb">
  * ✓ 描述具体的场景和动作
  * ✓ 包含光线、氛围、情绪等细节
  * ✓ 使用授权真人 ID（如 `@sama`）
  * ✗ 避免描述真实人脸
  * ✗ 避免过于简短的描述
</Card>

<Card title="模型选择建议" icon="layers">
  * **推荐：** `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)）
  * 基础模型稳定性都极高，可放心选择
</Card>

<Card title="错误处理建议" icon="shield-check">
  * 设置合理超时（建议 5 分钟）
  * 添加重试逻辑（最多 2-3 次）
  * 使用流式输出监控进度
  * 记录错误日志
</Card>

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

## 相关链接

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/api-capabilities/sora2/quick-start">
    查看示例代码和使用方法
  </Card>

  <Card title="模型定价" icon="tag" href="/api-capabilities/sora2/models-pricing">
    了解详细的模型对比和价格
  </Card>

  <Card title="使用示例" icon="code" href="/api-capabilities/sora2/examples">
    查看各种场景的应用示例
  </Card>

  <Card title="API 参考" icon="book" href="/api-capabilities/sora2/api-reference">
    查看完整的 API 文档
  </Card>
</CardGroup>