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

# Luma 视频接口参考

> Luma Dream Machine 视频生成接口

## 查询生成任务

`GET /luma/generations/{id}`

Luma 官方 API · 查询单个生成任务（`GET /luma/generations/`{`id`}\`\`）。

### 请求参数 (Query / Path)

<ParamField path="id" type="string" required>
  创建任务时返回的 id
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl "https://socialvision.tisyk.xyz/luma/generations/{id}" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
```

### 响应示例 (200 OK)

```json theme={null}
{
  "batch_id": "string",
  "created_at": "string",
  "estimate_wait_seconds": 0,
  "id": "string",
  "last_frame": {
    "url": "string"
  },
  "prompt": "string",
  "queue_state": "string",
  "state": "queued",
  "thumbnail": {
    "url": "string"
  },
  "video": {
    "height": 0,
    "url": "string",
    "width": 0
  }
}
```

***

## 延长视频

`POST /luma/generations/{id}/extend`

Luma 官方 API · 延长已有视频（`POST /luma/generations/`{`id`}`/extend`）。

### 请求参数 (Query / Path)

<ParamField path="id" type="string" required>
  原视频任务 ID
</ParamField>

### 请求体参数 (Body)

<ParamField body="prompt" type="string">
  延长部分的描述（可选）
</ParamField>

<ParamField body="user_prompt" type="string">
  延长部分的描述（代理格式）
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "user_prompt": "Continue the scene with the eagle landing on a cliff"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/luma/generations/{id}/extend" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "user_prompt": "Continue the scene with the eagle landing on a cliff"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "batch_id": "string",
  "created_at": "string",
  "estimate_wait_seconds": 0,
  "id": "string",
  "last_frame": {
    "url": "string"
  },
  "prompt": "string",
  "queue_state": "string",
  "state": "queued",
  "thumbnail": {
    "url": "string"
  },
  "video": {
    "height": 0,
    "url": "string",
    "width": 0
  }
}
```

***

## 创建视频生成任务

`POST /luma/generations`

Luma 官方 API · 创建视频生成任务（`POST /luma/generations`）。

文生视频或图生视频。支持两种请求格式：

* **官方格式**：`prompt` + `keyframes`
* **代理格式**：`user_prompt` + `image_url`

官方文档：[https://docs.lumalabs.ai/docs/video-generation](https://docs.lumalabs.ai/docs/video-generation)

### 请求体参数 (Body)

<ParamField body="duration" type="string">
  时长只支持5s
</ParamField>

<ParamField body="expand_prompt" type="boolean">
  可选，提示词优化开关
</ParamField>

<ParamField body="image_end_url" type="string">
  可选，目标关键帧图片
</ParamField>

<ParamField body="image_url" type="string">
  可选，参考图片来源
</ParamField>

<ParamField body="loop" type="boolean">
  可选，是否循环使用参考图
</ParamField>

<ParamField body="model_name" type="string">
  ray-v1、 ray-v2 官方显示是 ray1.6 ray2
</ParamField>

<ParamField body="notify_hook" type="string">
  可选，处理完成后的回调通知地址
</ParamField>

<ParamField body="resolution" type="string">
  720p或者1080p默认720p
</ParamField>

<ParamField body="user_prompt" type="string" required>
  必传，用户输入的提示词/问题描述
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "duration": "5s",
  "model_name": "ray-v2",
  "resolution": "720p",
  "user_prompt": "一阵风吹过树林，使女人的面纱微微飘动。"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/luma/generations" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "duration": "5s",
  "model_name": "ray-v2",
  "resolution": "720p",
  "user_prompt": "一阵风吹过树林，使女人的面纱微微飘动。"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "batch_id": "",
  "created_at": "2024-12-22T13:38:40.139Z",
  "id": "4665a07c-7641-4809-a133-10786201bb56",
  "prompt": "",
  "state": "pending"
}
```

***

## 批量查询任务

`POST /luma/tasks`

Luma 官方 API · 批量查询任务（`POST /luma/tasks`）。

根据 ID 列表批量查询多个任务状态。

"state": "completed" 枚举值： "pending", "processing", "completed", "failed"

### 请求体参数 (Body)

<ParamField body="aspect_ratio" type="string">
  生成图片的纵横比，可选，可选值：16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3
</ParamField>

<ParamField body="callback_url" type="string">
  回调通知地址，可选，当任务状态发生变化时，系统会向这个地址发送通知
</ParamField>

<ParamField body="ids" type="array" required>
  任务 ID 列表
</ParamField>

<ParamField body="image" type="string">
  参考图片，可选，支持 Base64 编码或图片 URL，支持 .jpg/.jpeg/.png 格式，大小不能超过 10MB
</ParamField>

<ParamField body="image_fidelity" type="number">
  参考图片的影响强度，可选，取值范围：0-1，值越大，生成的图像越接近参考图片
</ParamField>

<ParamField body="model" type="string">
  使用的模型，可选，默认为 kling-image
</ParamField>

<ParamField body="n" type="integer">
  生成图片的数量，可选，取值范围：1-9
</ParamField>

<ParamField body="negative_prompt" type="string">
  负向提示词，可选，描述你不想在图像中出现的元素，不能超过200个字符
</ParamField>

<ParamField body="prompt" type="string">
  正向提示词，必需，描述你想要生成的图像内容，不能超过500个字符
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/luma/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}'
```

### 响应示例 (200 OK)

```json theme={null}
[
  {
    "batch_id": "string",
    "created_at": "string",
    "estimate_wait_seconds": 0,
    "id": "string",
    "last_frame": {
      "url": "string"
    },
    "prompt": "string",
    "queue_state": "string",
    "state": "queued",
    "thumbnail": {
      "url": "string"
    },
    "video": {
      "height": 0,
      "url": "string",
      "width": 0
    }
  }
]
```

***

## 查询任务

`GET /luma/v1/task`

Luma GoAmz 兼容 · 查询任务（`GET /luma/v1/task`）。

### 请求体参数 (Body)

<ParamField body="ids" type="array" required>
  ID 列表
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl "https://socialvision.tisyk.xyz/luma/v1/task" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "status": "succeed"
  },
  "message": "success"
}
```

***

## 创建视频生成

`POST /luma/v1/generations`

Luma GoAmz 兼容 · 创建视频生成（`POST /luma/v1/generations`）。

### 请求体参数 (Body)

<ParamField body="aspect_ratio" type="string">
  宽高比，如 16:9、9:16、1:1
</ParamField>

<ParamField body="expand_prompt" type="boolean">
  是否扩展提示词
</ParamField>

<ParamField body="image_url" type="string">
  起始帧图片 URL
</ParamField>

<ParamField body="loop" type="boolean">
  是否循环
</ParamField>

<ParamField body="user_prompt" type="string" required>
  视频描述
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/luma/v1/generations" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "task_id": "task_example_001"
  },
  "message": "success"
}
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.