> ## 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. # API 参考 > Sora 2 视频生成 API 完整技术文档 ## 基础信息 **端点：** `https://api.yelinai.com/v1/chat/completions`**带水印端点：** `https://api.yelinai.com/v1/chat/completions?watermark=true`**方法：** `POST`**认证：** Bearer Token（API Key）**内容类型：** `application/json` **10/18 新增：带水印功能**默认生成的视频**无水印**。如需生成带 Sora 原生水印的视频，请在 URL 添加参数 `?watermark=true`。 ## 认证 在请求头中包含您的 API 密钥： ``` Authorization: Bearer YOUR_API_KEY ``` ## 请求格式 ### 基础结构 ``` { "model": "sora_video2", "messages": [ { "role": "user", "content": [...] } ], "stream": false } ``` ### 请求参数 | 参数 | 类型 | 必需 | 说明 | | ---------- | ------- | -- | ------------------- | | `model` | string | ✓ | 模型名称，见 [支持的模型](#) | | `messages` | array | ✓ | 消息数组 | | `stream` | boolean | ✗ | 是否启用流式输出，默认 `false` | ### Messages 数组 每个 message 对象包含： | 字段 | 类型 | 必需 | 说明 | | --------- | ------ | -- | ------------ | | `role` | string | ✓ | 固定为 `"user"` | | `content` | array | ✓ | 内容数组，包含文本或图片 | ### Content 数组 支持两种类型的内容： #### 文本内容 ``` { "type": "text", "text": "视频描述文字" } ``` | 字段 | 类型 | 必需 | 说明 | | ------ | ------ | -- | ------------ | | `type` | string | ✓ | 固定为 `"text"` | | `text` | string | ✓ | 视频生成提示词 | #### 图片内容（可选） ``` { "type": "image_url", "image_url": { "url": "https://example.com/image.png" } } ``` | 字段 | 类型 | 必需 | 说明 | | --------------- | ------ | -- | ----------------- | | `type` | string | ✓ | 固定为 `"image_url"` | | `image_url.url` | string | ✓ | 图片 URL 或 Base64 | **图片限制** * 最多 1 张图片 * 支持 URL 或 Base64 格式 * 推荐分辨率不超过 2048×2048 * 不支持真人照片 ## 支持的模型 | 模型名 | 分辨率 | 时长 | 价格 | | --------------------------- | ------------ | --- | ------ | | `sora_video2` | 704×1280（竖屏） | 10s | \$0.15 | | `sora_video2-landscape` | 1280×704（横屏） | 10s | \$0.15 | | `sora_video2-15s` | 704×1280（竖屏） | 15s | \$0.15 | | `sora_video2-landscape-15s` | 1280×704（横屏） | 15s | \$0.15 | \*\*价格更新（10/20）\*\*15秒模型已降价至 \$0.15/次，与10秒模型同价！ **高清HD模型**高清模型 `sora-2-pro`（HD 1080P，\$0.8/次）由于生成时间较长（约10分钟），仅支持异步API调用。👉 [查看异步API文档](/api-capabilities/sora2/async-api) ## 响应格式 ### 非流式响应 ```` { "id": "foaicmpl-xxx", "object": "chat.completion", "created": 1759759480, "model": "sora_video2", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "```json\n{\n \"prompt\": \"...\",\n \"mode\": \"竖屏模式\"\n}\n```\n\n> ✅ 视频生成成功，[点击这里](https://sora.gptkey.asia/assets/sora/xxx.mp4) 查看视频~~~\n\n" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 17, "completion_tokens": 244, "total_tokens": 261 } } ```` ### 响应字段说明 | 字段 | 类型 | 说明 | | --------------------------- | ------- | ------------------ | | `id` | string | 请求唯一标识 | | `object` | string | 对象类型 | | `created` | integer | 创建时间戳 | | `model` | string | 使用的模型 | | `choices[].message.content` | string | 包含视频链接的内容 | | `choices[].finish_reason` | string | 完成原因，`"stop"` 表示成功 | | `usage` | object | Token 使用统计 | ### 流式响应（SSE） 启用 `"stream": true` 时，返回 Server-Sent Events 格式： ```` data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1759759480,"model":"sora_video2","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]} data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1759759480,"model":"sora_video2","choices":[{"index":0,"delta":{"content":"```json\n{\n \"prompt\": \"...\"\n}\n```\n\n"},"finish_reason":null}]} data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1759759480,"model":"sora_video2","choices":[{"index":0,"delta":{"content":"> ⌛️ 任务正在队列中，请耐心等待...\n\n"},"finish_reason":null}]} data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1759759480,"model":"sora_video2","choices":[{"index":0,"delta":{"content":"> 🏃 进度：36.0%\n\n"},"finish_reason":null}]} data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1759759480,"model":"sora_video2","choices":[{"index":0,"delta":{"content":"> ✅ 视频生成成功，[点击这里](https://sora.gptkey.asia/assets/sora/xxx.mp4) 查看视频~~~\n\n"},"finish_reason":null}]} data: {"id":"foaicmpl-xxx","object":"chat.completion.chunk","created":1759759480,"model":"sora_video2","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":17,"completion_tokens":244,"total_tokens":261}} data: [DONE] ```` ### 流式响应字段 | 字段 | 类型 | 说明 | | ------------------------- | ------ | ---------------- | | `choices[].delta.role` | string | 角色，仅第一条消息包含 | | `choices[].delta.content` | string | 增量内容（进度或视频链接） | | `choices[].finish_reason` | string | 为 `"stop"` 时表示完成 | | `usage` | object | 最后一条消息包含使用统计 | ## 完整示例 ### 文生视频 cURL Python JavaScript ``` curl -X POST "https://api.yelinai.com/v1/chat/completions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "sora_video2", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "一只可爱的猫咪在阳光明媚的花园里玩球" } ] } ] }' ``` ### 图生视频（URL） cURL Python ``` curl -X POST "https://api.yelinai.com/v1/chat/completions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "sora_video2", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "生成视频：让这个手办形象从桌子上跳出来，变成活人的一个场景~" }, { "type": "image_url", "image_url": { "url": "https://filesystem.site/cdn/download/20250407/OhFd8JofOAJCsNOCsM1Y794qnkNO3L.png" } } ] } ] }' ``` ### 图生视频（Base64） Python ``` import openai import base64 client = openai.OpenAI( api_key="YOUR_API_KEY", base_url="https://api.yelinai.com/v1" ) # 读取本地图片 def encode_image(image_path): with open(image_path, "rb") as image_file: return base64.b64encode(image_file.read()).decode('utf-8') base64_image = encode_image("/path/to/image.png") response = client.chat.completions.create( model="sora_video2", messages=[ { "role": "user", "content": [ { "type": "text", "text": "让这个场景动起来" }, { "type": "image_url", "image_url": { "url": f"data:image/png;base64,{base64_image}" } } ] } ] ) print(response.choices[0].message.content) ``` ### 流式输出 Python JavaScript ``` import openai client = openai.OpenAI( api_key="YOUR_API_KEY", base_url="https://api.yelinai.com/v1" ) stream = client.chat.completions.create( model="sora_video2", messages=[ { "role": "user", "content": [ { "type": "text", "text": "一只可爱的猫咪在阳光明媚的花园里玩球" } ] } ], stream=True ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end='', flush=True) ``` ## 错误码 | HTTP 状态码 | 错误类型 | 说明 | | -------- | --------------------- | -------------- | | 400 | Bad Request | 请求参数错误 | | 401 | Unauthorized | API Key 无效或未提供 | | 402 | Payment Required | 余额不足 | | 429 | Too Many Requests | 请求过于频繁 | | 500 | Internal Server Error | 服务器内部错误 | | 503 | Service Unavailable | 服务暂时不可用 | ### 错误响应格式 ``` { "error": { "message": "错误描述", "type": "invalid_request_error", "code": "invalid_api_key" } } ``` ## 速率限制 目前暂无严格的速率限制，但建议： * 批量生成时控制并发数（建议 2-3 个） * 避免在短时间内大量请求 * 合理设置重试间隔 ## 最佳实践 超时设置 视频生成需要 2-4 分钟，建议设置超时时间为 **5-10 分钟**。 ``` import httpx import openai client = openai.OpenAI( api_key="YOUR_API_KEY", base_url="https://api.yelinai.com/v1", http_client=httpx.Client(timeout=300.0) # 5分钟 ) ``` 错误处理 添加重试逻辑处理临时错误： ``` import time max_retries = 3 for i in range(max_retries): try: response = client.chat.completions.create(...) break except Exception as e: if i < max_retries - 1: print(f"错误，{30}秒后重试...") time.sleep(30) else: raise ``` 视频下载 生成后立即下载（有效期 1 天）： ``` import requests import re # 提取链接 video_url = re.search(r'https://[^\s\)]+\.mp4', content).group(0) # 下载 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) ``` 流式输出监控 使用流式输出实时查看进度： ``` stream = client.chat.completions.create( model="sora_video2", messages=[...], stream=True ) for chunk in stream: if chunk.choices[0].delta.content: content = chunk.choices[0].delta.content print(content, end='', flush=True) ``` ## SDK 支持 ### 官方 SDK * **Python：** `openai` >= 1.0.0 * **Node.js：** `openai` >= 4.0.0 ### 第三方 SDK 任何兼容 OpenAI API 格式的 SDK 都可以使用，只需修改 `base_url`。 ## 技术规格 | 规格 | 值 | | ---------- | ----------------- | | **视频编码** | H.264 | | **音频编码** | AAC | | **帧率** | 24 fps | | **格式** | MP4 | | **水印** | 无 | | **音频** | 支持 | | **最大文件大小** | \~50MB（视时长和清晰度而定） | ## 下一步 ## 快速开始 查看快速开始指南 ## 使用示例 查看更多代码示例 ## 模型定价 了解模型对比和价格 ## 常见问题 查看常见问题解答