> ## 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 生图（历史接入）

> Sora 图像生成历史接入文档：说明旧线路的请求方式、模型 ID、比例参数与返回结果；新项目建议优先使用 GPT-Image-2。

<Warning>
  本页是 Sora Image 历史接入文档，供已接入旧线路的项目排查、迁移和兼容维护使用。新项目接入图片生成时，建议优先查看 [GPT-Image-2](/api-capabilities/gpt-image-2) 和 [图像生成 API 指南](/api-capabilities/image-generation-guide)。旧线路的可用性、价格和参数支持以控制台当前显示为准。
</Warning>

## 前置要求

<Steps>
  <Step title="获取 API Key">
    登录 [laozhang.ai 控制台](https://api2.laozhang.ai) 获取 API 密钥
  </Step>

  <Step title="配置计费模式">
    编辑令牌设置，选择以下任一计费模式。实际扣费规则以控制台当前配置为准：

    * **按量优先**（推荐）：优先使用余额计费，余额不足时自动切换。适合大多数用户
    * **按次计费**：每次调用直接扣费。适合预算控制严格的场景

    <Note>
      两种模式的区别在于扣费路径：按量优先会优先使用余额，按次计费会按调用扣费。请以控制台展示的当前价格为准。
    </Note>

    <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>
      如果未设置计费模式，API调用会失败。必须先完成此配置！
    </Warning>
  </Step>
</Steps>

## 模型简介

Sora Image 历史接入方案通过对话补全接口返回图片 URL，适用于仍在维护旧模型 ID 的项目。新项目应优先评估当前推荐的图像生成 API，实际可用性和计费规则以控制台为准。

<Note>
  **计费以控制台为准**\
  旧线路可能继续服务存量接入，但不建议在代码或文档中硬编码单张价格。请在接入前确认令牌分组、计费模式和当前模型状态。
</Note>

## 接口能力

* **旧模型 ID 兼容**：适用于仍在使用 `sora_image` 或 `gpt-4o-image` 的存量项目
* **对话补全接口**：通过 `/v1/chat/completions` 提交提示词并解析返回的图片 URL
* **比例参数**：支持 2:3、3:2、1:1 三种比例
* **URL 返回**：响应内容中返回可下载的图片链接
* **状态以控制台为准**：可用性、价格和参数支持可能随线路调整变化

## 模型信息

| 模型               | 模型 ID          | 计费方式   | 价格     | 特点       |
| ---------------- | -------------- | ------ | ------ | -------- |
| **Sora Image**   | `sora_image`   | 以控制台为准 | 以控制台为准 | 历史文生图模型  |
| **GPT-4o Image** | `gpt-4o-image` | 以控制台为准 | 以控制台为准 | 历史图像生成模型 |

<Tip>
  **迁移建议**\
  如果你正在新建图片生成能力，请先阅读 [图像生成 API 指南](/api-capabilities/image-generation-guide)。如果你在维护旧线路代码，请先确认当前令牌分组仍支持对应模型 ID。
</Tip>

## 🚀 快速开始

### 基础示例

```python theme={null}
import requests
import re

# API 配置
API_KEY = "YOUR_API_KEY"
API_URL = "https://api2.laozhang.ai/v1/chat/completions"

def generate_image(prompt, ratio="2:3"):
    """
    使用 Sora Image 生成图片

    Args:
        prompt: 图片描述文本
        ratio: 图片比例，支持 "2:3", "3:2", "1:1"
    """
    # 在提示词末尾添加比例标记
    if ratio and ratio in ["2:3", "3:2", "1:1"]:
        prompt = f"{prompt}【{ratio}】"

    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "model": "sora_image",
        "messages": [
            {
                "role": "user",
                "content": prompt
            }
        ]
    }

    response = requests.post(API_URL, headers=headers, json=payload)
    result = response.json()

    # 提取图片 URL
    content = result['choices'][0]['message']['content']
    image_urls = re.findall(r'!\[.*?\]\((https?://[^)]+)\)', content)

    return image_urls

# 使用示例
urls = generate_image("一只可爱的猫咪在花园里玩耍", "2:3")
print(f"生成的图片: {urls[0]}")
```

### 批量生成示例

```python theme={null}
def batch_generate_images(prompts, ratio="2:3"):
    """批量生成图片"""
    results = []

    for prompt in prompts:
        try:
            urls = generate_image(prompt, ratio)
            results.append({
                "prompt": prompt,
                "url": urls[0] if urls else None,
                "success": bool(urls)
            })
            print(f"✅ 成功生成: {prompt}")
        except Exception as e:
            results.append({
                "prompt": prompt,
                "url": None,
                "success": False,
                "error": str(e)
            })
            print(f"❌ 生成失败: {prompt} - {e}")

    return results

# 批量生成示例
prompts = [
    "夕阳下的海滩",
    "未来科技城市",
    "梦幻森林中的精灵"
]

results = batch_generate_images(prompts, "3:2")
```

## 📐 尺寸比例说明

Sora Image 支持三种预设比例，通过在提示词末尾添加比例标记来指定：

| 比例标记      | 尺寸比例 | 适用场景      | 示例           |
| --------- | ---- | --------- | ------------ |
| **【2:3】** | 竖版   | 人物肖像、手机壁纸 | `美丽的花朵【2:3】` |
| **【3:2】** | 横版   | 风景照片、横幅图片 | `壮观的山脉【3:2】` |
| **【1:1】** | 正方形  | 社交媒体头像、图标 | `可爱的小狗【1:1】` |

### 尺寸使用示例

```python theme={null}
# 竖版人像
portrait = generate_image("优雅的女士肖像，专业摄影风格【2:3】")

# 横版风景
landscape = generate_image("日出时分的山谷，光线柔和【3:2】")

# 正方形图标
icon = generate_image("简约现代的应用图标设计【1:1】")
```

## 🎯 最佳实践

### 1. 提示词优化

```python theme={null}
# ❌ 不推荐：过于简单
prompt = "猫"

# ✅ 推荐：详细描述
prompt = """
一只毛茸茸的橘色猫咪，
坐在阳光明媚的窗台上，
背景是模糊的城市景观，
摄影风格，高清细节
【2:3】
"""
```

### 2. 错误处理

```python theme={null}
import time

def generate_with_retry(prompt, max_retries=3):
    """带重试机制的图片生成"""
    for attempt in range(max_retries):
        try:
            urls = generate_image(prompt)
            if urls:
                return urls[0]
        except Exception as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # 指数退避
                print(f"重试 {attempt + 1}/{max_retries}，等待 {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise e

    return None
```

### 3. 结果保存

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

def save_generated_image(url, prompt):
    """保存生成的图片到本地"""
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    filename = f"sora_{timestamp}.png"

    response = requests.get(url)
    with open(filename, 'wb') as f:
        f.write(response.content)

    # 保存提示词信息
    with open(f"sora_{timestamp}_prompt.txt", 'w', encoding='utf-8') as f:
        f.write(f"Prompt: {prompt}\n")
        f.write(f"URL: {url}\n")
        f.write(f"Time: {datetime.now()}\n")

    return filename
```

## 💡 高级技巧

### 1. 风格化生成

```python theme={null}
# 艺术风格模板
art_styles = {
    "油画": "油画风格，厚重的笔触，丰富的色彩层次",
    "水彩": "水彩画风格，透明感，色彩流动",
    "素描": "铅笔素描风格，黑白，细腻的线条",
    "动漫": "日本动漫风格，大眼睛，鲜艳的色彩",
    "写实": "超写实摄影，高清细节，专业摄影"
}

def generate_with_style(subject, style_name):
    """使用预设风格生成图片"""
    style = art_styles.get(style_name, "")
    prompt = f"{subject}，{style}【2:3】"
    return generate_image(prompt)

# 使用示例
url = generate_with_style("美丽的玫瑰花", "水彩")
```

### 2. 场景模板

```python theme={null}
# 场景生成模板
def generate_scene(subject, time="日落", weather="晴朗", mood="宁静"):
    """根据参数生成场景图片"""
    prompt = f"""
    {subject}
    时间：{time}
    天气：{weather}
    氛围：{mood}
    摄影风格，专业构图
    【3:2】
    """
    return generate_image(prompt.strip())

# 生成不同场景
sunset_beach = generate_scene("海滩", "日落", "微风", "浪漫")
morning_forest = generate_scene("森林小径", "清晨", "薄雾", "神秘")
```

### 3. 批量主题变体

```python theme={null}
def generate_variations(base_prompt, variations, ratio="2:3"):
    """生成同一主题的多个变体"""
    results = []

    for variation in variations:
        full_prompt = f"{base_prompt}，{variation}【{ratio}】"
        try:
            url = generate_image(full_prompt)[0]
            results.append({
                "variation": variation,
                "url": url,
                "prompt": full_prompt
            })
        except Exception as e:
            print(f"变体生成失败: {variation}")

    return results

# 生成猫咪的不同变体
base = "一只可爱的猫咪"
variations = [
    "橘色虎斑",
    "黑白奶牛色",
    "纯白色长毛",
    "灰色短毛"
]

cat_variations = generate_variations(base, variations)
```

## 预算估算建议

旧线路的价格和计费方式以控制台当前配置为准。上线前建议按以下步骤核对成本：

1. 在控制台确认当前令牌分组是否仍支持 `sora_image` 或 `gpt-4o-image`
2. 查看该分组对应的计费模式和当前单价
3. 使用你的预计调用量乘以控制台单价，预估批量任务预算
4. 为生产调用设置调用量监控和失败重试上限

## ⚠️ 使用限制

1. **请求频率**：建议控制在 10 请求/分钟以内
2. **提示词长度**：建议不超过 500 字符
3. **比例限制**：仅支持 2:3、3:2、1:1 三种比例
4. **内容审核**：自动过滤不当内容请求

## 🔍 常见问题

### Q: 为什么价格这么成本较低？

A: 历史线路的计费方式和当前推荐图像模型不同。实际价格请以控制台为准，不建议依赖旧文档中的历史价格判断成本。

### Q: 图片质量如何？

A: 图片效果取决于提示词、比例和当前模型状态。新项目建议优先评估当前推荐的图像生成模型，再根据质量、成本和稳定性选择接入路线。

### Q: 支持哪些语言？

A: 支持中文和英文提示词。建议在生产环境中使用固定测试集验证提示词稳定性。

### Q: 图片版权问题？

A: 生成的图片可用于商业用途，但建议避免生成涉及版权的内容。

## 🎨 效果展示

以下是一些使用 Sora Image 生成的示例效果：

| 提示词      | 比例  | 效果描述       |
| -------- | --- | ---------- |
| 赛博朋克城市夜景 | 3:2 | 霓虹灯光、未来感建筑 |
| 梦幻独角兽    | 2:3 | 粉色系、童话风格   |
| 日式禅意庭院   | 1:1 | 极简、宁静氛围    |

## 🔗 相关资源

* [完整示例代码](https://github.com/laozhang-api/ai-api-code-samples/tree/main/sora_image-API)
* [图像编辑 API](/api-capabilities/sora-image-edit) - 使用 Sora 编辑现有图片
* [GPT-Image-1 API](/api-capabilities/gpt-image-1) - 官方接口的图像生成
* [在线测试工具](https://yingtu.ai) - 比较不同模型效果

<Note>
  🚀 **快速开始**：注册 老张API 账号即可获得测试额度，立即体验 Sora Image 的强大功能！
</Note>