# 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>