# Luma

### 创建视频

{% hint style="info" %}
Luma视频`fast模式`一般来说将会在300s内返回，具体时效取决于prompt的复杂度\
`relax模式`一般会在1分钟至30分钟之间内返回，具体时效取决于官方的算力紧张程度
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.ttapi.io/luma/v1/generations`

通过文字&图片生成视频

**Headers**

| Name         | Value                  |
| ------------ | ---------------------- |
| Content-Type | `application/json`     |
| TT-API-KEY   | `用于请求授权 TT-API 的API密钥` |

**Body**

<table><thead><tr><th width="178">参数</th><th width="108">类型</th><th width="116">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>userPrompt</td><td>string</td><td>是</td><td>生成视频的文字提示，例：a red car driving on a road，<a href="../../faq/luma#ru-he-you-hua-wo-de-prompt-da-dao-wo-xiang-yao-de-xiao-guo">具体参考</a><br><strong>注意：luma官方支持多语言，但是经尝试还是英文的生成效果最佳，使用时请自行斟酌</strong></td></tr><tr><td>imageUrl</td><td>string</td><td>否</td><td>开始帧图片链接，使用该参数，视频开始的第一帧会以该图片为影像，<a href="../../faq/luma#ru-he-shi-yong-kai-shi-zhen-he-jie-shu-zhen-tu-pian-sheng-cheng-shi-pin">具体效果详见</a></td></tr><tr><td>imageEndUrl</td><td>string</td><td>否</td><td>结束帧图片链接，使用该参数，视频结束的最后一帧会以该图片为影像，<a href="../../faq/luma#ru-he-shi-yong-kai-shi-zhen-he-jie-shu-zhen-tu-pian-sheng-cheng-shi-pin">具体效果详见</a><br><strong>注意：该参数仅当模型使用 ray-v1 时生效</strong> </td></tr><tr><td>hookUrl</td><td>string</td><td>否</td><td>回调地址，任务完成或失败将通过请地址进行通知，<a href="#yi-bu-hui-tiao-json-jie-gou-hookurl-json">通知数据结构</a>与fetch结构一致。如果未设置，则需要请求<a href="#cha-xun-shi-pin-jie-guo">fetch接口</a>进行查询。</td></tr><tr><td>loop</td><td>boolean</td><td>否</td><td>是否生成无限循环的视频，可选值为false或者true。<strong>默认false</strong><br>PS：无限循环可以理解为开始的第一帧与结束帧相同</td></tr><tr><td>aspectRatio</td><td>string</td><td>否</td><td>视频比例<br>支持：9:16 3:4 1:1 4:3 16:9 21:9，默认9:16</td></tr><tr><td>modelName</td><td>string</td><td>否</td><td>使用模型<br>支持：<br>ray-v1 <br>ray-v2 <br>ray-v2-flash<br>ray-v3<br>ray-v3-reasoning<br>默认 ray-v3</td></tr><tr><td>duration</td><td>string</td><td>否</td><td>视频时长<br>支持:  5s  10s 默认5s，注意：<strong>10s的视频仅在720p的清晰度下生效</strong></td></tr><tr><td>resolution</td><td>string</td><td>否</td><td>清晰度<br>支持：720p 1080p 默认720p</td></tr><tr><td>useMode</td><td>string</td><td>否</td><td>速度模式<br>支持：fast， relax 默认为relax模式，注意不同模式定价不同，<a href="../../ttapi-zhong-wen-wen-dang#luma-ding-jia">详见</a></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "SUCCESS",
  "message": "",
  "data": {
    "jobId": "ed1a1b01-7d64-4c8a-acaa-71185d23a2f3"
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "status": "FAILED",
  "message": "error message",
  "data": {}
}
```

{% endtab %}
{% endtabs %}

### 视频延伸

<mark style="color:green;">`POST`</mark> `https://api.ttapi.io/luma/v1/extend`

在上一条视频的基础上延伸生成一条视频，该接口的[具体作用详见](https://docs-zh.mjapiapp.com/faq/luma#shi-pin-yan-shen-jie-kou-shi-yong-lai-zuo-shen-me-de)

**Headers**

| Name         | Value                  |
| ------------ | ---------------------- |
| Content-Type | `application/json`     |
| TT-API-KEY   | `用于请求授权 TT-API 的API密钥` |

**Body**

<table><thead><tr><th width="178">参数</th><th width="108">类型</th><th width="116">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>jobId</td><td>string</td><td>是</td><td>上一个生成的视频的jobId</td></tr><tr><td>userPrompt</td><td>string</td><td>是</td><td>生成视频的文字提示，例：a red car driving on a road<br><strong>注意：luma官方支持多语言，但是经尝试还是英文的生成效果最佳，使用时请自行斟酌</strong></td></tr><tr><td>hookUrl</td><td>string</td><td>否</td><td>回调地址，任务完成或失败将通过请地址进行通知，<a href="#yi-bu-hui-tiao-json-jie-gou-hookurl-json">通知数据结构</a>与fetch结构一致。如果未设置，则需要请求<a href="#cha-xun-shi-pin-jie-guo">fetch接口</a>进行查询。</td></tr><tr><td>modelName</td><td>string</td><td>否</td><td>使用模型<br>支持：<br>ray-v1 <br>ray-v2 <br>ray-v2-flash<br>ray-v3<br>ray-v3-reasoning<br>默认 ray-v3</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "SUCCESS",
  "message": "",
  "data": {
    "jobId": "ed1a1b01-7d64-4c8a-acaa-71185d23a2f3"
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "status": "FAILED",
  "message": "error message",
  "data": {}
}
```

{% endtab %}
{% endtabs %}

### 查询视频结果

<mark style="color:green;">`GET`</mark> `https://api.ttapi.io/luma/v1/fetch`

通过jobId查询当前视频生成结果

**Headers**

| Name         | Value                  |
| ------------ | ---------------------- |
| Content-Type | `application/json`     |
| TT-API-KEY   | `用于请求授权 TT-API 的API密钥` |

**Query参数**

<table><thead><tr><th width="178">参数</th><th width="108">类型</th><th width="116">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>jobId</td><td>String</td><td>是</td><td>生成的视频的jobId</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "SUCCESS",
    "message": "success",
    "jobId": "6eb34b44-64c8-4629-a0a1-608737de9583",
    "data": {
        "jobId": "6eb34b44-64c8-4629-a0a1-608737de9583",
        "userPrompt": "Sanrio style illustration of Hello Kitty dressed ",
        "width": "512",
        "height": "512",
        "imageUrl": null,
        "imageEndUrl": null,
        "videoFirstFrame": "",
        "videoLastFrame": "",
        "hookUrl": "https://webhook-test.com/72b9baa490830671b5cd068815788b7e",
        "videoUrl": "https://storage.cdn-luma.com/lit_lite_inference_im2vid_v1.0/11be9408-f349-46df-a43e-a3b57002c1cd/watermarked_video09312742f491e41c19974b52babdba615.mp4"
    }
}
```

{% endtab %}
{% endtabs %}

### 异步回调JSON结构 HookUrl JSON

异步回调josn结构与fetch接口查询返回结构一致

```
{
    "status": "SUCCESS",
    "message": "success",
    "jobId": "6eb34b44-64c8-4629-a0a1-608737de9583",
    "data": {
        "jobId": "6eb34b44-64c8-4629-a0a1-608737de9583",
        "userPrompt": "Sanrio style illustration of Hello Kitty dressed ",
        "width": "512",
        "height": "512",
        "imageUrl": null,
        "imageEndUrl": null,
        "videoFirstFrame": "",
        "videoLastFrame": "",
        "hookUrl": "https://webhook-test.com/72b9baa490830671b5cd068815788b7e",
        "videoUrl": "https://storage.cdn-luma.com/lit_lite_inference_im2vid_v1.0/11be9408-f349-46df-a43e-a3b57002c1cd/watermarked_video09312742f491e41c19974b52babdba615.mp4",
        "quota": 3
    }
}
```

### 结果参数详解

<table><thead><tr><th width="189">参数</th><th>详解</th></tr></thead><tbody><tr><td>status</td><td>结果状态，<br>ON_QUEUE：执行中<br>SUCCESS：成功<br>FAILED：失败</td></tr><tr><td>videoUrl</td><td>视频地址，国内可直接访问</td></tr><tr><td>quota</td><td>实际消耗额度</td></tr><tr><td>imageUrl</td><td>用户上传开始帧图片地址</td></tr><tr><td>imageEndUrl</td><td>用户上传结束帧图片地址</td></tr><tr><td>videoFirstFrame</td><td>Luma返回视频开始封面图片</td></tr><tr><td>videoLastFrame</td><td>Luma返回视频结尾封面图片</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-zh.mjapiapp.com/api/luma.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.