用现有 SDK 接入
火山图片与视频
使用拉镜 Key,base_url 为 https://api.lashot.tianyunai.com/compat/ark/api/v3。拉镜统一提供模型调用、鉴权、项目授权、任务归档及费用结算。使用平台模型标识,不能沿用自己在火山创建的 ep-... 接入点。
火山方舟 SDK 对接的是拉镜的统一协议入口,与模型的执行渠道无关。模型在平台完成接入并开放后,可按已支持的方法调用,无需因为渠道调整而更换 SDK 或调用地址。各模型的版本、参数和参考素材能力以当前模型目录为准;同名模型出现多个条目时,使用目录返回的完整平台模型标识。文本、语音及其他 SDK 资源的支持范围见下文。
安装官方 Python 包 pip install volcengine-ark-runtime,导入 from volcenginesdkarkruntime import Ark。客户端设置 max_retries=0,为每笔逻辑请求保存唯一 Idempotency-Key,发生网络中断时先查询原任务,避免重新生成新的付费任务。
带远程参考素材的调用还需要 assets:write,以便拉镜在当前项目内导入素材;仅文生图、文生视频不需要此导入权限。
import os, uuid
from volcenginesdkarkruntime import Ark
client = Ark(api_key=os.environ["LASHOT_KEY"],
base_url="https://api.lashot.tianyunai.com/compat/ark/api/v3",
max_retries=0, timeout=90)
# 将此值与订单一起持久化;同一次逻辑调用始终使用同一个值。
request_key = str(uuid.uuid4())
image = client.images.generate(model="seedream-4.5", prompt="一座海边灯塔",
size="2K", response_format="url",
extra_headers={"Idempotency-Key": request_key})
print(image)
video = client.content_generation.tasks.create(model="seedance-1.0-pro-fast",
content=[{"type":"text", "text":"海边灯塔,镜头缓慢向前移动"}],
duration=2, resolution="480p", ratio="16:9",
extra_headers={"Idempotency-Key": str(uuid.uuid4())})
print(client.content_generation.tasks.get(task_id=video.id))
图片模型:seedream-4.5、seedream-5.0-lite、seedream-5.0-pro、seedream-5.5。视频模型:seedance-1.0-pro-fast、seedance-1.0-pro、seedance-1.5-pro、seedance-2.0-mini、seedance-2.0-fast、seedance-2.0-select、seedance-2.0、seedance-2.0-fast-value、seedance-2.0-value、seedance-2.5-select、seedance-2.5、seedance-2.5-value。
size 按当前模型契约转换,4.5 支持 2K/4K、5.0 Lite 支持 2K/3K、5.0 Pro 支持 1K/2K;5.5 支持基础生成尺寸与像素档计费。图片参考使用 image HTTPS URL 或 URL 数组;视频使用 content 中的 image_url / video_url / audio_url,以及 first_frame、last_frame、reference_image、reference_video、reference_audio 角色,具体受模型槽位限制。远程素材先进入受保护导入链路;私有素材先导入并使用统一 API 的资产引用,不向外部 URL 携带平台 Key。可用 SDK 的 extra_body={"project_id":"项目UUID"} 指定项目。
同步图片请求最多等待约 60 秒;若收到 202 或空结果,读取 lashot_job_id,通过 GET /v1/jobs/{id} 查询,不能当成生成成功或重新提交。视频通过 tasks.get 查询终态。stream=true、Base64 返回、连续组图与 5.5 图层分离尚未开放,会明确拒绝。文本 doubao-seed-2.1-pro、语音 seed-audio-1.0、素材审核 seedance-human-review 使用拉镜统一 POST /v1/generations,不表示 Ark Chat、音频等所有 SDK 资源均兼容。计费按客户已绑定套餐与任务冻结版本执行,参数档和输入素材会影响实际费用。
已经在用火山方舟、通义万相、可灵、MiniMax 或百度千帆的官方调用方式时,可以复用已支持的请求字段,把地址和 Key 换成 lashot。私有媒体的下载还需按下文接入鉴权。
将 $LASHOT_BASE 设置为你实际部署的 API 地址。本地开发可用 http://localhost:8080;正式环境地址请向部署管理员确认。本文不代表公共生产服务已上线。
在控制台 密钥 页创建 Key,填进原来 SDK 的 api_key 槽位。生成和查询需要 generations:write/read;读取媒体还需要 assets:read 及当前项目访问权限。
改哪两处
| 你正在用 | 把 base URL 改成 |
|---|---|
| 火山方舟 Ark | $LASHOT_BASE/compat/ark/api/v3 |
| 通义万相 DashScope | $LASHOT_BASE/compat/dashscope/api/v1 |
| 可灵 Kling | $LASHOT_BASE/compat/kling/v1 |
| MiniMax | $LASHOT_BASE/compat/minimax |
| 百度千帆 | $LASHOT_BASE/compat/qianfan/v2 |
鉴权仍用各家 SDK 习惯的写法;服务端同时接受 Authorization: Bearer 与 x-api-key。
只接受已开放的模型与字段,多出来的参数会 400。新私有项目的结果地址是 /v1/asset-versions/{id}/content 形式的根相对路径:按 $LASHOT_BASE 的 API origin 解析,向该精确同源内容路径发送当前 Bearer Key。每次下载都重新检查项目权限和媒体审核,不向外部存储 URL 发送平台凭据,不带凭据跟随重定向。原厂无鉴权下载器需要增加这个适配,不能仅改地址和 Key 就认为媒体下载完整兼容。
最短示例(方舟出图)
沙箱模型在方舟入口里叫 sandbox-image(对应 lashot 的 sandbox/image)。
curl -sS -X POST "$LASHOT_BASE/compat/ark/api/v3/images/generations" \
-H "Authorization: Bearer $LASHOT_KEY" \
-H "content-type: application/json" \
-d '{
"model": "sandbox-image",
"prompt": "a lighthouse at dusk, long exposure",
"size": "1024x1024",
"response_format": "url"
}'
Python 方舟 SDK 的请求示例(打印任务或结果,尚未下载文件):
from volcenginesdkarkruntime import Ark
import os
client = Ark(
base_url=os.environ["LASHOT_BASE"] + "/compat/ark/api/v3",
api_key=os.environ["LASHOT_KEY"],
)
print(client.images.generate(
model="sandbox-image",
prompt="a lighthouse at dusk, long exposure",
size="1024x1024",
response_format="url",
))
同步接口最多等约 60 秒;超时会 202,用返回的任务 id 再查。异步接口(视频等)按各家原来的「创建任务 → 查任务」循环即可。
接下来
- 新项目、或不想跟某一家字段:走 lashot 接口。
- 查全部方法和字段:控制台 全部接口。