> ## 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.

# 最佳实践（自定义 API - 已过时）

> 优化 VEO API 使用效果的建议和技巧 - 旧版文档

<Warning>
  **⚠️ 此文档为旧版自定义 API，不推荐使用**

  新版旧接入入口为 [Veo-3.1 最佳实践](/api-capabilities/veo/veo-31-best-practices)，但 Veo-3.1 旧接入方案自 2026 年 5 月 14 日起暂时无法使用。当前请暂停按旧版 VEO3 自定义 API 新增生产接入；如需要当前可用的 Veo 3.1 视频生成入口，请优先查看 [Veo 3.1 官方 API 转发方案](/api-capabilities/veo/official-forward)。
</Warning>

## 提示词编写指南

编写高质量的提示词是获得优秀视频的关键。以下是各个要素的详细说明：

### 提示词结构

<Tabs>
  <Tab title="主体描述">
    明确描述视频的主要对象或角色

    **好的示例：**

    * "一只橘色的小猫"
    * "穿着红色连衣裙的年轻女孩"
    * "银色的跑车"

    **避免：**

    * "某个东西"
    * "一些动物"
  </Tab>

  <Tab title="动作行为">
    具体描述主体的动作和行为

    **好的示例：**

    * "慢慢走动"
    * "快速奔跑"
    * "优雅地跳舞"

    **避免：**

    * "在移动"
    * "做某事"
  </Tab>

  <Tab title="环境场景">
    详细描述背景和环境

    **好的示例：**

    * "阳光明媚的花园"
    * "雨夜的城市街道"
    * "日落时分的海滩"

    **避免：**

    * "某个地方"
    * "外面"
  </Tab>

  <Tab title="镜头运动">
    描述摄像机的运动方式

    **好的示例：**

    * "镜头跟随"
    * "俯拍视角"
    * "360度环绕"

    **可选元素**
  </Tab>

  <Tab title="画质风格">
    指定期望的视觉风格

    **好的示例：**

    * "4K高清，电影级"
    * "动画风格"
    * "复古胶片质感"

    **可选元素**
  </Tab>
</Tabs>

### 优秀提示词示例

<Accordion>
  <AccordionItem title="自然场景">
    ```
    一只橘色的小猫在阳光明媚的花园里慢慢走动，
    花瓣在微风中轻舞，镜头跟随猫咪的步伐，
    4K高清，电影级画质，暖色调
    ```
  </AccordionItem>

  <AccordionItem title="城市场景">
    ```
    雨夜的东京街头，霓虹灯光反射在湿润的地面上，
    一位撑着透明雨伞的女孩穿过人行横道，
    赛博朋克风格，电影级调色
    ```
  </AccordionItem>

  <AccordionItem title="动作场景">
    ```
    专业滑板运动员在城市滑板公园展示高难度技巧，
    慢动作捕捉空中翻转瞬间，夕阳余晖照射，
    运动摄影风格，高帧率
    ```
  </AccordionItem>

  <AccordionItem title="产品展示">
    ```
    最新款智能手表在纯白背景中360度旋转展示，
    特写镜头展现金属质感和屏幕细节，
    产品摄影风格，极简主义
    ```
  </AccordionItem>
</Accordion>

## 提示词增强功能

<Info>
  开启 `enhance_prompt` 可以让 AI 自动优化您的提示词，提高生成质量
</Info>

### 何时使用提示词增强

<CardGroup cols={2}>
  <Card title="推荐使用" icon="check">
    * 初次使用 API
    * 提示词较简单
    * 想要更好的效果
    * 不确定如何描述
  </Card>

  <Card title="可以关闭" icon="x">
    * 需要精确控制
    * 已有完善提示词
    * 特定风格要求
    * 技术性描述
  </Card>
</CardGroup>

## 参考图片使用

### 图片要求

| 要求  | 说明              |
| --- | --------------- |
| 格式  | JPG、PNG、WebP    |
| 大小  | 单张不超过 10MB      |
| 数量  | 最多 5 张          |
| 分辨率 | 建议 1024x1024 以上 |
| 内容  | 清晰、相关的参考素材      |

### 使用技巧

<Steps>
  <Step title="选择高质量图片">
    使用清晰、高分辨率的图片作为参考
  </Step>

  <Step title="保持风格一致">
    多张图片应保持视觉风格的一致性
  </Step>

  <Step title="相关性优先">
    选择与目标视频最相关的参考图片
  </Step>

  <Step title="避免冲突">
    图片内容不应与文字描述产生冲突
  </Step>
</Steps>

## 轮询策略

### 推荐的轮询实现

```python theme={null}
import time
import math

def exponential_backoff_polling(client, task_id, initial_interval=5, max_interval=60):
    """
    指数退避轮询策略
    """
    interval = initial_interval
    attempt = 0
    
    while True:
        try:
            status_data = client.get_status(task_id)
            status = status_data.get('status')
            
            if status == 'completed':
                return status_data['result']
            elif status == 'failed':
                raise Exception(f"生成失败: {status_data.get('error')}")
            
            # 指数退避
            time.sleep(interval)
            attempt += 1
            interval = min(initial_interval * math.pow(1.5, attempt), max_interval)
            
        except Exception as e:
            print(f"轮询出错: {e}")
            time.sleep(interval)
```

### 轮询参数建议

<Note>
  * **初始间隔：** 5 秒
  * **最大间隔：** 60 秒
  * **退避因子：** 1.5
  * **最大等待：** 30 分钟
</Note>

## 错误处理

### 重试策略

```python theme={null}
def retry_with_backoff(func, max_retries=3, backoff_factor=2):
    """
    带退避的重试机制
    """
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            
            wait_time = backoff_factor ** attempt
            print(f"失败，{wait_time}秒后重试...")
            time.sleep(wait_time)
```

### 常见错误处理

<Tabs>
  <Tab title="网络错误">
    ```python theme={null}
    try:
        result = client.submit_task(prompt)
    except requests.exceptions.ConnectionError:
        print("网络连接失败，请检查网络")
    except requests.exceptions.Timeout:
        print("请求超时，请稍后重试")
    ```
  </Tab>

  <Tab title="API 错误">
    ```python theme={null}
    try:
        result = client.submit_task(prompt)
    except Exception as e:
        if "QUOTA_EXCEEDED" in str(e):
            print("配额已用完")
        elif "INVALID_PROMPT" in str(e):
            print("提示词无效")
    ```
  </Tab>

  <Tab title="任务失败">
    ```python theme={null}
    status = client.get_status(task_id)
    if status['status'] == 'failed':
        error_info = status.get('error', {})
        print(f"任务失败: {error_info.get('message')}")
        # 可以尝试重新提交
    ```
  </Tab>
</Tabs>

## 性能优化

### 批量处理

当需要生成多个视频时，建议使用批量处理：

```python theme={null}
async def batch_process_videos(prompts, max_concurrent=5):
    """
    批量处理视频生成
    """
    semaphore = asyncio.Semaphore(max_concurrent)
    
    async def process_one(prompt):
        async with semaphore:
            return await client.submit_and_wait(prompt)
    
    tasks = [process_one(prompt) for prompt in prompts]
    return await asyncio.gather(*tasks)
```

### 资源管理

<Warning>
  注意并发限制：同时最多 10 个任务
</Warning>

## 成本优化

### 模型选择策略

```python theme={null}
def choose_model(requirements):
    """
    根据需求智能选择模型
    """
    if requirements.get('need_fast'):
        return 'veo3-fast'
    elif requirements.get('high_quality'):
        return 'veo3-pro'
    elif requirements.get('precise_control'):
        return 'veo3-pro-frames'
    else:
        return 'veo3'  # 默认选择标准版
```

### 测试建议

<Tip>
  开发阶段使用 `veo3` 或 `veo3-fast` 进行测试，生产环境根据需要选择合适的模型
</Tip>

## 监控和日志

### 建议的日志记录

```python theme={null}
import logging
from datetime import datetime

class VEOLogger:
    def __init__(self):
        self.logger = logging.getLogger('veo_api')
        
    def log_task_submission(self, task_id, prompt, model):
        self.logger.info(f"Task submitted: {task_id}")
        self.logger.debug(f"Prompt: {prompt[:50]}...")
        self.logger.debug(f"Model: {model}")
        
    def log_task_completion(self, task_id, duration, video_url):
        self.logger.info(f"Task completed: {task_id}")
        self.logger.info(f"Duration: {duration}s")
        self.logger.debug(f"Video URL: {video_url}")
```

### 监控指标

* 任务成功率
* 平均生成时间
* API 响应时间
* 错误率统计
* 费用追踪