Runway Gen-4 Turbo API 怎么接？提交图生视频任务并核对完成状态

Runway 图生视频 API 会先创建异步任务，返回任务 ID；拿到 ID 后，还要等状态变为 SUCCEEDED、检查输出地址并下载视频。本文固定 Gen-4 Turbo，输入一张你有权使用的参考图，生成五秒短片，不把创建成功当成视频已经完成。

以下接口按 2026-10-01 官方文档和 runwayml 5.20.1 的真实 SDK 方法核对。已在本地检查脚本语法、SDK 参数路径和未成功状态的拒绝逻辑；没有 Runway 开发者令牌，未提交真实生成任务，也没有视频效果与调用耗时实测。

准备开发者环境和参考图

官方模型表把 Gen-4 Turbo 对应为 gen4_turbo，输入是图像、输出是视频。它的模型名和示例中的 Gen-4.5 不同；调用时应保留本文明确选择的模型，而不是照抄其他模型字段。

按照官方 API 指南创建开发者凭证，在本机环境配置 RUNWAYML_API_SECRET，另外把你自己的 HTTPS 参考图地址放在 RUNWAY_IMAGE_URL。参考图需要服务端可访问，浏览器里能看到的登录后私有地址不一定可读。

在独立环境安装 runwayml==5.20.1。本例横向输出 ratio=1280:720、duration=5，提示词只描述轻微推进镜头与叶片移动。把代码保存为 runway_video.py，执行 python runway_video.py。

import json
import os
from pathlib import Path
from urllib.request import urlopen
from runwayml import RunwayML, TaskFailedError

def successful_output(task):
    if task.status != 'SUCCEEDED':
        raise ValueError(f'Task is not succeeded: {task.status}')
    if not task.output or not task.output[0].startswith('https://'):
        raise ValueError('Succeeded task lacks an HTTPS output URL')
    return task.output[0]

def main():
    image_url=os.environ['RUNWAY_IMAGE_URL']
    if not image_url.startswith('https://'):
        raise ValueError('Set RUNWAY_IMAGE_URL to your accessible HTTPS reference image')
    client=RunwayML(max_retries=0)
    task=client.image_to_video.create(model='gen4_turbo',prompt_image=image_url,
        prompt_text='A gentle camera push in, leaves moving slightly in the breeze.',
        ratio='1280:720',duration=5)
    Path('runway_task.json').write_text(json.dumps({'id':task.id},indent=2),encoding='utf-8')
    print('created_task_id:',task.id)
    try:
        completed=task.wait_for_task_output()
    except TaskFailedError as error:
        print('task_failed:', error.task_details)
        raise
    output_url=successful_output(completed)
    with urlopen(output_url,timeout=90) as response:
        data=response.read()
    if not data:
        raise ValueError('Downloaded output is empty')
    temp=Path('runway_video.mp4.part')
    temp.write_bytes(data)
    temp.replace('runway_video.mp4')
    print('task_status:',completed.status)
    print('saved: runway_video.mp4')
    print('bytes:',len(data))

if __name__=='__main__':
    main()

任务 ID、最终状态和下载分三步核对

create 返回后立刻把真实任务 ID 保存到 runway_task.json；网络恢复时可用它核对已有任务。
wait_for_task_output 等待结果后，代码再要求 status 为 SUCCEEDED，且 output 至少有一个 HTTPS 地址。
下载得到非空数据后，先写临时文件，再保存 runway_video.mp4；随后实际打开视频检查。

官方输出说明规定，成功任务在 output 中提供下载 URL，地址在访问后约 24–48 小时内到期，需要及时下载到自己的存储。不要把临时签名地址当作永久公开视频地址。

任务失败说明用于解释生成失败；本例捕获 TaskFailedError 并保留失败信息。等待超时或连接中断属于“结果仍待核对”，不应记成成功，也不应立即再创建同一内容。

怎样判断短片兑现了输入要求

实际成功运行后，核对 task_status: SUCCEEDED、非零文件大小以及播放器能正常打开。再查看开头、中间和结尾：参考主体是否保持、镜头是否轻微推进、画面是否突然换景、是否存在不自然变形。程序获得非空数据并不证明生成效果合格。

如果图片读取失败，先检查 URL 是否公开、是否真的返回图像，以及当前模型的图片输入限制。认证或额度错误先修正账户问题；内容错误需要核对提示词与素材。不要只替换模型名就假定其他字段仍兼容。

中途断线怎样继续核对

保留已经保存的 ID，用 client.tasks.retrieve(task_id)读取该任务当前状态；确认成功后取 output，确认失败后读失败信息。如果创建请求在返回 ID 之前断线，结果未知，应先核对开发者项目记录，避免盲目重复生成。本例关闭 SDK 自动重试，便于把创建行为和恢复决策分开。

正式接入还要设置等待期限、预算和恢复策略；短片视觉结果仍需逐段检查。本文提供调用与验收流程，没有保证模型对某张图片的主体一致性、动作质量或生成时长表现。

Ai菜鸟网。发布者：AI小管家，转载请注明出处：https://www.alyyhw.com/31873.html