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

# Sora 视频生成

> 使用 `POST /v1/videos` 调用 Sora 模型提交异步视频任务。

# Sora 视频生成

Sora 当前通过 `POST /v1/videos` 提交异步视频任务。

* 请求体推荐使用 JSON。
* 文生视频只需要 `model`、`prompt`、`size`、`seconds`。
* 首帧/参考图生视频使用 `input_reference`。
* 比例和分辨率使用顶层 `size`。

## 当前模型

* `sora-2`
* `sora-2-pro`

## 方法与路径

```http theme={null}
POST /v1/videos
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2",
      "prompt": "猫咪听歌摇头晃脑，下大雨",
      "size": "1280x720",
      "seconds": "12"
    }'
  ```

  ```bash 参考图生视频 cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2",
      "prompt": "让参考图中的主体自然动起来，保持构图和电影感光影",
      "size": "1280x720",
      "seconds": "12",
      "input_reference": "https://example.com/reference.png"
    }'
  ```

  ```bash 竖屏视频 cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2",
      "prompt": "雨夜街头的电影感跟拍镜头，人物撑伞向前走",
      "size": "720x1280",
      "seconds": "8"
    }'
  ```

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

  resp = requests.post(
      "https://www.geeknow.top/v1/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "sora-2",
          "prompt": "猫咪听歌摇头晃脑，下大雨",
          "size": "1280x720",
          "seconds": "12",
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://www.geeknow.top/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "sora-2",
      prompt: "猫咪听歌摇头晃脑，下大雨",
      size: "1280x720",
      seconds: "12",
    }),
  });

  console.log(await response.json());
  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	payload := map[string]interface{}{
  		"model":   "sora-2",
  		"prompt":  "猫咪听歌摇头晃脑，下大雨",
  		"size":    "1280x720",
  		"seconds": "12",
  	}

  	body, err := json.Marshal(payload)
  	if err != nil {
  		panic(err)
  	}

  	req, err := http.NewRequest("POST", "https://www.geeknow.top/v1/videos", bytes.NewReader(body))
  	if err != nil {
  		panic(err)
  	}
  	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
  	req.Header.Set("Content-Type", "application/json")

  	resp, err := http.DefaultClient.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	respBody, err := io.ReadAll(resp.Body)
  	if err != nil {
  		panic(err)
  	}
  	fmt.Println(string(respBody))
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class Main {
      public static void main(String[] args) throws Exception {
          String json = """
          {
            "model": "sora-2",
            "prompt": "猫咪听歌摇头晃脑，下大雨",
            "size": "1280x720",
            "seconds": "12"
          }
          """;

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://www.geeknow.top/v1/videos"))
              .header("Authorization", "Bearer YOUR_API_KEY")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(json))
              .build();

          HttpResponse<String> response = HttpClient.newHttpClient()
              .send(request, HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://www.geeknow.top/v1/videos');

  $payload = [
      'model' => 'sora-2',
      'prompt' => '猫咪听歌摇头晃脑，下大雨',
      'size' => '1280x720',
      'seconds' => '12',
  ];

  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer YOUR_API_KEY',
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode($payload),
      CURLOPT_RETURNTRANSFER => true,
  ]);

  $response = curl_exec($ch);
  if ($response === false) {
      throw new RuntimeException(curl_error($ch));
  }

  curl_close($ch);
  echo $response;
  ```
</RequestExample>

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "video_abc123",
    "task_id": "video_abc123",
    "object": "video",
    "model": "sora-2",
    "status": "queued",
    "progress": 0,
    "created_at": 1735689600,
    "size": "1280x720",
    "seconds": "12"
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "sora-2 size is invalid",
      "type": "new_api_error",
      "param": "",
      "code": "invalid_size"
    }
  }
  ```
</ResponseExample>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  模型名称。当前支持 `sora-2` 和 `sora-2-pro`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频生成提示词。
</ParamField>

<ParamField body="size" type="string">
  目标尺寸。`sora-2` 支持 `720x1280`、`1280x720`；`sora-2-pro` 支持 `720x1280`、`1280x720`、`1792x1024`、`1024x1792`。建议显式传入，避免依赖上游默认值。
</ParamField>

<ParamField body="seconds" type="string | integer">
  目标秒数。推荐以字符串传入，例如 `"4"`、`"8"`、`"12"`。部分 OpenAI/OAI Sora 渠道只接受 `4`、`8`、`12`。
</ParamField>

<ParamField body="duration" type="integer">
  兼容字段。未传 `seconds` 时会被作为秒数使用。
</ParamField>

<ParamField body="input_reference" type="string | array<string>">
  参考图输入。JSON 中可传图片 URL、base64 或 data URI。
</ParamField>

<ParamField body="metadata" type="object">
  供应商扩展参数。
</ParamField>

## 当前规则

| 项目                | 规则                                            |
| ----------------- | --------------------------------------------- |
| 默认尺寸              | 建议请求中显式传 `size`，避免依赖默认值                       |
| `sora-2` 尺寸校验     | `720x1280`、`1280x720`                         |
| `sora-2-pro` 尺寸校验 | `720x1280`、`1280x720`、`1792x1024`、`1024x1792` |
| 时长校验              | 部分 OAI 渠道限制为 `4`、`8`、`12` 秒                   |
| 参考图格式             | JSON 可用 URL、base64、data URI                   |

## 相关接口

* [Sora 视频概览](./overview)
* [Sora 任务查询](./query)