NXAI 文档

Appearance

Sora-2（创建视频） ​

POST  v1/video

v1/videos 接口核心必选参数为 model/prompt/duration/resolution，其余为可选增强配置；

prompt 支持精细化描述（时长、镜头、风格、氛围），是视频生成效果的核心控制项；

不同 Sora-2 版本对应不同的时长 / 分辨率上限，需匹配参数避免报错；

input_media 可传入参考素材，weight 参数控制素材参考程度，适合定制化场景；

异步场景建议配置 webhook_url，同步场景直接接收返回的视频 URL 即可。

请求参数 ​

Authorization ​

在 Header 添加参数 Authorization，其值为在 Bearer 之后拼接 Token。

Authorization: Bearer ******************

Body 参数 ​

Content-Type: application/json

参数名类型必填说明
modelstring必需模型 ID。指定使用的视频生成模型版本。
promptstring必需提示词。描述期望生成的视频内容、动作和场景。
durationinteger必需视频时长。生成视频的持续时间（通常以秒为单位）。
resolutionstring必需分辨率。视频的清晰度规格（例如 "1024x576", "720p"）。
fpsinteger必需帧率。每秒显示的帧数，影响视频的流畅度。
style_presetstring必需风格预设。预定义的视觉风格标签（例如 "cinematic", "anime", "3d-model"）。
aspect_ratiostring必需宽高比。视频画面的比例（例如 "16:9", "9:16"）。
guidance_scaleinteger必需引导系数。控制模型对提示词的遵循程度，值越高越贴合提示词但可能降低多样性。
response_formatstring必需响应格式。指定返回数据的格式（如 "mp4", "gif" 或数据编码格式）。
num_variationsinteger必需变体数量。一次性生成的视频版本数量，便于用户从中挑选最佳结果。

请求示例 (JSON) ​

{
  "model": "sora-2",
  "prompt": "A realistic 1080p video of a surfer riding a wave at sunrise, ocean waves crash gently, golden light on the water, camera follows the surfer from behind, 30 seconds long, calm and peaceful atmosphere",
  "duration": 30,
  "resolution": "1080p",
  "fps": 30,
  "style_preset": "cinematic",
  "aspect_ratio": "16:9",
  "guidance_scale": 8.0,
  "response_format": "mp4",
  "num_variations": 1
}

返回响应 ​

200 成功

Content-Type: application/json

响应参数 ​

字段名类型必填说明
idstring必需任务 ID。本次生成任务的唯一标识符。
objectstring必需对象类型。通常为 "video.generation"。
createdinteger必需创建时间戳。任务创建时的 Unix 时间戳。
modelstring必需模型名称。执行此任务的模型 ID（例如 veo-3.1-generate-preview）。
statusstring必需最终状态。此时应为 "SUCCEEDED" 或 "COMPLETED"。
dataarray [object]必需结果数据数组。包含生成的视频文件信息。
├─ video_idstring可选视频 ID。视频资源的内部标识符。
├─ urlstring可选视频下载链接。生成的视频文件的访问地址。
├─ expires_atinteger可选过期时间戳。链接失效的时间。
├─ formatstring可选文件格式。例如 "mp4"。
├─ resolutionstring可选分辨率。例如 "1920x1080"。
├─ duration_actualinteger可选实际时长。视频的实际播放时长（秒）。
├─ fpsinteger可选帧率。每秒帧数。
├─ aspect_ratiostring可选宽高比。例如 "16:9"。
├─ size_bytesinteger可选文件大小。视频文件占用的字节数。
└─ variation_indexinteger可选变体索引。如果是批量生成多个视频，表示这是第几个。
metadataobject可选元数据。包含生成时的配置信息。
├─ promptstring必需提示词。用于生成视频的原始文本提示。
├─ negative_promptstring必需反向提示词。生成时使用的负面提示词。
├─ stylestring必需风格。使用的风格预设。
├─ seedinteger必需种子值。生成时使用的随机种子。
└─ guidance_scaleinteger必需引导系数。生成时使用的引导比例。
generation_time_secondsnumber必需生成耗时。实际处理该任务花费的时间（秒）。
usageobject必需用量统计。关于 Token 消耗的统计信息。
├─ prompt_tokensinteger必需提示词 Token。输入文本消耗的 Token 数。
├─ video_tokensinteger必需视频 Token。生成视频内容消耗的 Token 数。
├─ total_tokensinteger必需总 Token 数。此次请求的总消耗量。
└─ duration_billed_secondsinteger必需计费时长。用于计费的视频时长（秒）。
errornull必需错误信息。如果成功则为 null；如果失败则包含错误详情。

响应示例 ​

{
  "id": "video-8e7b9c2d1a3f4e5d8b7a6c9e8b7d6a5f",
  "object": "video.completion",
  "created": 1735689600,
  "model": "sora-2",
  "status": "completed",
  "data": [
    {
      "video_id": "vid-1234567890abcdef",
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/org-xxxx/user-xxxx/video-8e7b9c2d1a3f4e5d8b7a6c9e8b7d6a5f.mp4?se=2026-02-13T08%3A00%3A00Z&sig=xxxx&sp=r&sr=b&sv=2021-08-06",
      "expires_at": 1736899200,
      "format": "mp4",
      "metadata": {
        "resolution": "1080p",
        "duration": 30.0,
        "fps": 30,
        "aspect_ratio": "16:9",
        "style_preset": "cinematic",
        "camera_movement": "tracking",
        "seed": 458921763,
        "guidance_scale": 8.0
      },
      "size_bytes": 185423987,
      "variation_index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 128,
    "video_tokens": 45600,
    "total_tokens": 45728,
    "duration_seconds_billed": 30
  },
  "metadata": {
    "prompt": "A realistic 1080p video of a surfer riding a wave at sunrise, ocean waves crash gently, golden light on the water, camera follows the surfer from behind, 30 seconds long, calm and peaceful atmosphere",
    "generation_time_seconds": 45.2,
    "model_version": "sora-2-202601"
  },
  "error": null
}

示例代码 ​

python
import http.client
import json

conn = http.client.HTTPSConnection("nxaiapp.com")
payload = json.dumps({
   "model": "sora-2",
   "prompt": "A realistic 1080p video of a surfer riding a wave at sunrise, ocean waves crash gently, golden light on the water, camera follows the surfer from behind, 30 seconds long, calm and peaceful atmosphere",
   "duration": 30,
   "resolution": "1080p",
   "fps": 30,
   "style_preset": "cinematic",
   "aspect_ratio": "16:9",
   "guidance_scale": 8,
   "response_format": "mp4",
   "num_variations": 1
})
headers = {
   'Authorization': 'Bearer <token>',
   'Content-Type': 'application/json'
}
conn.request("POST", "/v1/videos", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))