跳转到文档
v4v.开发者文档预览版您的 API 密钥 ↗
本指南内容
身份验证发现 LAB 模型带时间轴的语音字幕最新生成模型Kling 4.0 视频模型GPT-6 Astra 聊天使用外部图片的实验室上传私有媒体使用外部或私有媒体的工作室任务和点数重命名和整理项目幂等性已签名回调错误和限制Studio 批量生成(API 和 MCP)
可供测试
直接访问预览
API reference · v1

使用 V4V API 进行创作。

可从你自己的应用中生成图像、视频和音频。一个 API 密钥。使用你现有的 V4V 点数。

开始使用 →下载 OpenAPI ↓
端点https://v4v.ai/api/v1
cURL
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
01

身份验证#

在“个人资料 → API 密钥”中创建一个具名密钥。API secret 和 webhook 签名 secret 出现时请保存;它们只显示一次。可以独立创建和撤销多个密钥。密钥 secret 以 SHA-256 哈希形式存储。

每个 API 请求都要发送 Authorization: Bearer v4v_live_…。请将此密钥保存在你的服务器上,不要放在浏览器应用或源代码管理中。撤销后会阻止未来请求;已接受的生成会继续执行。

基础 URL:https://v4v.ai/api/v1。

02

发现 LAB 模型#

GET /models 列出当前 LAB 模型 ID、启用状态、输入、参数、默认值、条件和限制。GET /models/{model} 描述单个模型。ID 和 schema 来自与 LAB 相同的目录和默认值。Studio 配置是独立的。

下方示例中的模型名称均为实际目录 ID。请使用 discovery 查找你账户当前已启用的模型。字段名因模型而异:请保留 discovery 返回的名称,包括诸如 aspectRatio 或 referenceImageUrls 这样的 camelCase 名称。选择项的值是字符串;对于看起来像数字的选择项,也接受数值类型。字段可以放在 input 或 parameters 中,但不能同时出现在两者中。未知字段会被拒绝。带可选版本的模型会暴露 parameters.variant;请使用 discovery 返回的取值和默认值。

bash
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
03

带时间轴的语音字幕#

通过类型 subtitle 发现 ai.speech_to_text。在 input.audioUrl 或 input.videoUrl 中提交你拥有的媒体文件 ID 或受支持的 URL 到 POST /lab;可选参数包括 language_code(例如 uk、en 或 auto)和 diarize。预估基于原始源时长。转录会消耗账户的常规点数。

已完成任务会返回 results[].type: "subtitle"、转录文本 text、srt,以及可编辑的 cues,其中包含以秒为单位的 start、end 和 text。成功的静音输入可能会返回空的提示列表。对于蒙太奇,请使用视频编辑器的 MCP 工具将这些提示对齐到源片段的裁剪、速度和时间线位置。

04

最新生成模型#

Omni Flash 1.2(video.gemini_omni_flash-1-2)是未显式指定模型的视频请求的首选模型。实验室会将其列在首位;Omni Flash 1.1 仍可在“更多”中找到,也可通过其现有 ID 使用。请使用 GET /models/{model} 发现当前参数。1.2 版本支持 3–15 秒的生成与编辑;首帧/尾帧插值仅限 10 秒。共享的 4/6/8/10 秒资费与已配置的 1.1 价格一致。价格请以当前 discovery 和 estimates 为准,不要将这种对应关系固化为永久规则。

在 image.text_to_image 或 ai.image_edit 中通过 parameters.variant 选择 GPT Image 2.6。请使用 parameters.outputFormat,并遵循以下精确的变体能力:

变体输出格式
gpt-image-2.6-flare-textpng、jpeg、webp、gif、svg
gpt-image-2.6-sunburst-textpng、jpeg、webp、gif、svg
gpt-image-2.6-flare-imgpng、jpeg、webp
gpt-image-2.6-sunburst-imgpng、jpeg、webp
gpt-image-2.6-economy-textpng、gif
gpt-image-2.6-economy-imgpng

parameters_schema.outputFormat.allowed_by_variant 为最终依据。Flare/Sunburst 按实际输入/输出用量结算;SVG 转换用量计入最终总额。Economy 仅支持 1K,且按每张图片计费。下载内容会保留 GIF 帧和 SVG 向量字节;SVG 下载使用 attachment 方式传输。

Nano Banana 2.1 在相同的图像模块中使用 parameters.variant: "nano-banana-v2.1",支持最多 10 个参考图以及 1K/2K/4K 输出。其当前计费模式发布在 pricing_by_variant 中。Google/Vertex 生成按已验证输入、缓存输入、图像输出、文本输出和 thinking tokens 结算,应用加价后,对合计总额统一向上取整一次。图像输出部分在计入输入和 thinking 之前,1K/2K/4K 约为 11/16/36 V4V 点数。实验室和预估会显示一个近似区间;初始预留与最终费用分开。其他路由使用已配置的按图计费资费。路由仍由 V4V 管理;请不要传入路由参数。

Gemini 4 Argon(chat.gemini_4_argon)也可通过实验室、工作流和 API/MCP 使用。其输入、缓存输入、输出和 thinking 用量会在响应后结算。请从模型 discovery 中读取当前价格、上线日期和费率调整。

05

Kling 4.0 视频模型#

四个独立节点在实验室、工作流、API 和 MCP 中共享相同的生成与结果处理方式:

目录 ID模型时长分辨率
video.kling_v40_refKling 4.0 Reference3–30 秒720p / 1080p
video.kling_v40_keyKling 4.0 Keyframe3–30 秒720p / 1080p
video.kling_v40_flash_refKling 4.0 Flash Reference3–20 秒720p
video.kling_v40_flash_keyKling 4.0 Flash Keyframe3–20 秒720p

全部都接受必填的 prompt(最多 8000 个字符)、整数 duration、resolution 和 aspectRatio(auto、16:9、9:16、1:1、21:9;Flash Keyframe 不包含 auto)。全部都可以仅从文本生成。Reference 输入为可选。

Reference 模型接受 referenceImageUrls(最多 10 个)、referenceVideoUrls(最多 5 个)、elements(最多 7 个,若含视频则最多 3 个)和 keepOriginalSound。一个命名元素包含 name、imageUrls(2–4 张图片)或 videoUrl(一段 3–8 秒的角色片段)二选一、可选的 tag、description(100 个字符)以及角色 voiceUrl。Flash 还接受元素 type(image 或 video)。标准 Reference 还接受 voices:最多 3 个对象,每个包含 name 和 audioUrl。Flash 则改为将声音绑定到角色元素。

图片、视频参考、元素和独立声音合计最多 15 个;参考视频与视频元素合计不能超过 5 个。每个参考视频必须为 2–30 秒(Flash 为 2–20 秒),且它们与视频元素合计的总时长最多为 30 秒(Flash 为 20 秒)。名称在忽略大小写时必须唯一,且为 1–20 个中文字符、字母、数字或下划线;内置参考名称为保留名称。请将提供的参考写作 @image_1、@video_1 或它们声明的 @name。未声明的提及将被拒绝。

Keyframe 模型使用 firstFrameUrl。标准 Keyframe 还接受有序的 keyframeUrls(最多 8 个中间帧)和 lastFrameUrl;这些都要求提供首帧。总帧数不能超过 min(duration + 1, 10)。Flash Keyframe 仅支持首帧。提及帧时请使用 @first_frame、@keyframe_1、@last_frame。基于帧的输出会遵循首张图片的宽高比。

所有媒体字段(包括嵌套的元素和声音)在 API/MCP 中都接受 URL 或你拥有的 V4V 文件 ID。工作流图片/视频端口使用 / ,或 / / ;提示词使用 。标准 Reference 还支持在 上传音频,并声明为 、 等。两个工作流输出都是标准的 / ,适用于现有渲染器和编辑器。API/MCP 会返回常规的异步任务和可下载结果文件;请轮询任务或使用完成 webhook。

06

GPT-6 Astra 聊天#

使用 GET /models/chat.gpt_6_astra 发现 chat.gpt_6_astra(slug:gpt-6-astra)。它的类型为 chat,并返回文本。discovery 包含 token 费率和取整规则。

json
{
  "model": "chat.gpt_6_astra",
  "input": {
    "prompt": "Explain what is in this image.",
    "imageUrls": [
      "https://example.com/image.png"
    ]
  },
  "parameters": {
    "reasoningEffort": "high",
    "webSearch": true,
    "stream": false
  }
}

Send this body to POST /lab. Images are optional; up to 12 URLs or owned file IDs are accepted. Text-only requests use string input upstream; image requests use an array of message content. Reasoning effort: low, medium, high, xhigh (default low). Web search and streaming default to false. Streamed responses are returned as a completed task after generation finishes.

若要提供函数,请将 input.functionTools 作为 JSON 字符串传入,其中包含 1–10 个定义,并带有 type: "function"、name、description 和 parameters(一个对象 JSON Schema)。将 parameters.webSearch 设为 false。上游请求使用 tool_choice: "auto";函数请求会通过 results[].function_calls 返回,供你的应用处理。模型节点不会执行函数,也不会在获得函数结果后继续对话。

聊天在进入队列前会预留 1 点数。这是最低预留,不是固定价格,也不是支出上限。每 1M tokens 的费率为:输入 560、缓存输入 56、缓存写入 700、输出 2,800 点数。合计 token 成本会统一向上取整一次到整数点数,且最低收费为 1。响应后,任何额外费用都会以原子方式从可用余额中扣除。若余额不足,任务会失败,未使用的预留将被释放。

对于按用量计费的聊天和图片,estimate 端点还会返回 credits_range,其中包含 min、max、assumptions、includes_markup: true、is_estimate: true 和 is_spending_cap: false。请将其显示为以 V4V 点数表示的近似区间。它包含当前加价和价格调整。这些只是示例用量场景;实际成本可能超出该区间。credits_estimated 和 initial_reservation_estimated 会单独描述初始预留。该区间不会改变按实际用量结算,也不会启用硬预算准入。

GET /tasks/{task_id} 和完成回调会直接返回内联文本,无需媒体文件:

json
{
  "status": "completed",
  "credits_reserved": 3,
  "credits_used": 3,
  "results": [
    {
      "type": "text",
      "text": "The image shows…",
      "incomplete": false,
      "function_calls": [],
      "usage": {
        "input_tokens": 4443,
        "uncached_input_tokens": 4443,
        "cached_input_tokens": 0,
        "cache_write_tokens": 0,
        "output_tokens": 47
      },
      "credits": 3
    }
  ]
}

反映结算后的扩展预留。 表示已达到输出上限;已消耗的 tokens 仍会计费。重复轮询或使用相同的幂等键重试,不会产生新的收费。

07

使用外部图片的实验室#

媒体输入在同一字段中既接受外部 URL,也接受 V4V 文件 ID。数组中可以混用两者。URL 必须直接返回真实媒体文件,不能依赖浏览器 cookie 或交互式登录。建议使用 HTTPS 和有效期足够长的签名 URL。V4V 会在生成前验证并复制外部媒体;内部网络 URL 和不安全的重定向会被拒绝。

bash
curl https://v4v.ai/api/v1/lab \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: product-edit-001' \
  -d '{"model":"ai.image_edit","input":{"prompt":"Place this product on a marble counter","referenceImageUrls":["https://example.com/product.jpg"]},"parameters":{"variant":"nano-banana-2","aspectRatio":"9:16","resolution":"2K"}}'
08

上传私有媒体#

POST /files 接受一个使用 multipart/form-data 的 file 字段。支持图片、视频和音频,但受模型限制。默认上传上限为 100 MiB,且还会受到部署的存储上传限制和代理限制的进一步约束。文件必须包含可解码的媒体;音频/视频检测要求服务器上安装 ffprobe。

bash
curl https://v4v.ai/api/v1/files \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -F 'file=@product.png'
json
{
  "id": "6aa962444bd1dd7ab65bc6b6",
  "type": "image",
  "content_type": "image/png",
  "size": 123456
}

请直接使用返回的 ID,不要加 file_ 前缀。GET /files/{id} 可在不消耗点数的情况下查询你文件的元数据。

json
{
  "model": "ai.image_edit",
  "input": {
    "prompt": "Create a studio product photograph",
    "referenceImageUrls": [
      "6aa962444bd1dd7ab65bc6b6",
      "https://example.com/side.jpg"
    ]
  },
  "parameters": {
    "variant": "nano-banana-2"
  }
}
09

使用外部或私有媒体的工作室#

POST /studio 使用与工作室 UI 相同的已选工作室工作流、预处理、模型执行、价格乘数和订阅折扣。

json
{
  "input": {
    "product_name": "Example Product",
    "product_description": "Lightweight everyday backpack",
    "product_images": [
      "https://example.com/front.jpg",
      "6aa962444bd1dd7ab65bc6b6"
    ],
    "prompt": "Show the product in everyday use"
  },
  "parameters": {
    "duration": 10,
    "aspect_ratio": "9:16",
    "style": "UGC",
    "language": "en",
    "avatar": null
  },
  "callback_url": "https://partner.example/webhooks/v4v"
}

若要实现完全私有媒体流程,请先使用 POST /files 上传每张产品图片,然后将返回的 ID 放入 input.product_images。头像、音频和视频参考也以相同方式上传。

工作室接受 product_id(你拥有的已保存产品)、avatar_id(你拥有的或当前启用的公共素材库头像,支持 public: 前缀)、product_name、product_description、prompt、product_images、reference_images、avatar_media、audio 和 video。每个媒体字段都接受引用;数组支持多个文件。parameters.avatar 接受素材库头像 ID、单个图片 URL 或文件 ID,或 null。请在 input.avatar_id 和 parameters.avatar 中二选一。显式产品字段会覆盖素材库默认值。活动样式名称/ID 会应用已保存的样式指令。未知、未启用和空样式值会返回 422 INVALID_PARAMETER、field: "parameters.style" 和 error.allowed_values,其中包含当前启用的 ID/名称。省略 style 时,将使用当前默认值(若 UGC 已启用则用 UGC,否则使用第一个启用的预设)。参数还包括 style、language、voice、placement、duration、aspect_ratio 和 quality。

针对以前在 parameters.style 中传入自由文本的客户端的迁移方式:请将这些创意指引移到 input.prompt 中,并从 MCP describe_studio 选择一个已启用样式(或省略 style 以使用当前默认值)。拼写错误的样式不再被当作自定义样式。

所选工作流决定限制。ProVid 支持 4–15 的整数秒、480p/720p/1080p,以及 9:16、16:9、1:1、4:5、4:3、3:4、21:9、adaptive 比例。OmniVid 支持 4/6/8/10 秒、360p/720p/1080p/4k,以及 9:16 或 16:9。新的 OmniVid 工作室请求默认使用 720p 和 10 秒,除非显式提供设置。无效选项会返回验证错误。媒体组合限制同样适用。OmniVid 在 LAB 中支持音频参考 ID,但在工作室中不接受原始音频参考文件;不受支持的参考会返回验证错误。

10

任务和点数#

生成在输入校验完成后返回 HTTP 202,并且在容量可用时完成点数预留;它不会等待生成完成:

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6",
  "status": "queued",
  "credits_reserved": 20,
  "created_at": "2026-09-15T18:00:00Z"
}

可选项目名称

POST /lab 和 POST /studio 都接受位于顶层的 project_name,与 input、parameters 和 callback_url 同级:

json
{
  "project_name": "Summer campaign — product photo",
  "model": "image-upscale-topaz",
  "input": {
    "image_url": "https://example.com/product.png"
  },
  "parameters": {
    "upscale_factor": "2"
  }
}

去除首尾空白后的名称(1–200 个字符,且不能为空)会成为“项目”中的标题;对于 LAB,则会成为“旧运行”中的标题。若省略,则使用现有默认标题。任务响应会包含 project_name 和 project_id。如果使用相同幂等键更改名称,会产生冲突,就像更改生成输入一样。

任务状态

服务器会在后台刷新生成状态。轮询返回最新保存的 status:queued、processing、completed、failed 或 cancelled。当任务处于 queued 或 processing 时,请显示加载指示器。当 status 为 completed 时,从 results[].text 读取聊天文本,或从 results 下载媒体文件。对于 failed,请检查 error(包括已知情况下失败的 stage、brief_completed、retryable 和建议的 retry_after_seconds)以及 credits_used。成功的 brief 生成在渲染失败时仍可能保留其收费;瞬时恢复提示不会启动或授权新的付费尝试。cancelled 也是终态。

Webhooks 为可选项。如果没有 callback_url,请每隔 3–5 秒重复以下请求,直到 status 为 completed、failed 或 cancelled:

bash
curl "$V4V_BASE_URL/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $V4V_API_KEY"

完成后,直接读取内联文本结果;媒体文件请从 results[].url 下载。在生成文件正在保存时,任务会保持为 processing;仅生成成功并不等于任务完成。请重复状态请求以刷新已过期的下载 URL。轮询不会启动新的生成,也不会扣除点数。

轮询 GET /tasks/{task_id},或提供一个回调 URL。状态包括 queued、processing、completed、failed 或 cancelled。轮询需要使用与该任务同一账户所拥有的 API key。

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6",
  "source": "lab",
  "status": "completed",
  "credits_used": 18,
  "results": [
    {
      "type": "video",
      "url": "https://v4v.ai/api/v1/results/…",
      "content_type": "video/mp4",
      "size": 18392832,
      "expires_at": "2026-09-16T00:00:00Z"
    }
  ]
}

每个媒体结果都包含稳定的 和 值。在后续生成的媒体输入中使用 。响应还包含 。结果列表支持多个图片、视频和音频文件。结果链接带签名,无需 V4V cookie 或身份验证即可使用。请再次获取任务状态以续期已过期的链接。可复用性的保证是稳定的文件 ID 加可续期的签名 URL,前提是存储文件仍存在且访问仍被允许;它不是永久不变的公开 URL。若要在次日复用结果,请再次解析相同的任务/文件 ID,并通过新的 URL 下载。任何持有结果链接的人都可在其过期前使用它。

11

重命名和整理项目#

项目整理使用与 Projects 工作区相同的文件夹。它不会生成媒体、预留点数,也不会更改生成输入、结果或幂等性哈希。所有操作都需要你的 API 密钥,且只会访问你账户中的项目和文件夹。

方法和路径用途
GET /projects查找 Studio、工作流 和 LAB 项目,包括排队中的 API 任务
PATCH /projects/{project_id}重命名项目和/或将其移动到文件夹
GET /project-folders列出工作区文件夹
POST /project-folders使用 {"name":"Summer campaign"} 创建文件夹
PATCH /project-folders/{folder_id}使用 {"name":"Autumn campaign"} 重命名文件夹

两个列表端点都接受 offset(默认 0)和 limit(1–100,默认 50),并返回 total 和 next_offset(最后一页为 null)。项目按最新优先排序,并以稳定 ID 作为并列时的次级排序;文件夹按名称排序。项目筛选项为 source=all|studio|workflow|lab、q(按字面值、不区分大小写的标题搜索,最多 200 个字符)和 folder_id(当前账户拥有的文件夹 ID,或用 unfiled 表示无文件夹)。省略 folder_id 可包含所有文件夹。

GET /projects 返回 projects,其中包含 project_id、project_name、source、folder_id(字符串或 null)、status、created_at 和 updated_at。状态反映原始项目或 LAB 历史;生成状态请使用 GET /tasks/{task_id}。更新时请使用返回的 project_id;没有对应项目的旧版 LAB 条目会使用其 LAB 运行 ID。GET /project-folders 返回 folders,其中包含 folder_id、name、color、created_at 和 updated_at。

bash
# Discover projects and folders.
curl -H "Authorization: Bearer $V4V_API_KEY" \
  'https://v4v.ai/api/v1/projects?source=studio&limit=50'
curl -H "Authorization: Bearer $V4V_API_KEY" \
  'https://v4v.ai/api/v1/project-folders'

# Supply real IDs returned by the list endpoints.
curl -X PATCH "https://v4v.ai/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $V4V_API_KEY" -H 'Content-Type: application/json' \
  -d '{"project_name":"Summer campaign — approved","folder_id":"YOUR_FOLDER_ID"}'
12

幂等性#

提交 LAB 或 Studio 请求时,请发送 Idempotency-Key(1–200 个字符)。相同账户、相同键值、相同端点和相同 JSON 内容会返回原始任务,即使该账户下使用的是不同 API 密钥也是如此。对象属性顺序会被忽略。对不同内容重复使用同一个键会返回 HTTP 409 IDEMPOTENCY_CONFLICT。如果原始请求仍在校验中,HTTP 409 REQUEST_IN_PROGRESS 会要求你使用相同键重试。被拒绝的提交仍会与其键关联;请使用新键修正后重新提交。

持久唯一索引可防止并发重试创建出另一条生成或预留记录。幂等性记录会随任务历史一起保留。

13

已签名回调#

提供一个可选的公开 callback_url。V4V 会推送 task.completed 或 task.failed,其中包含任务字段、结果列表和稳定的 event_id。回调带有 X-V4V-Timestamp 和 X-V4V-Signature: v1=<hex> 请求头。请使用创建 API 密钥时显示的 webhook 签名密钥进行验证。

签名是对时间戳、一个字面量句点以及精确原始请求体计算得到的 HMAC-SHA256。请拒绝过期时间戳(例如超过五分钟),并以常量时间比较签名。

javascript
import crypto from 'node:crypto';
const expected = crypto.createHmac('sha256', webhookSecret)
  .update(`${timestamp}.${rawBody}`).digest('hex');
const valid = /^v1=[a-f0-9]{64}$/.test(signature)
  && Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  && crypto.timingSafeEqual(Buffer.from(signature.slice(3), 'hex'), Buffer.from(expected, 'hex'));

请及时返回 2xx 响应。投递至少一次:请按 event_id 去重。网络故障、超时、HTTP 408/429 和 5xx 响应会按指数退避重试,从 30 秒开始,最长一小时,默认最多 12 次。其他非成功响应(包括重定向)会停止投递。重试绝不会创建生成或扣除点数。如果回调投递次数耗尽,请轮询任务状态。

Studio 批量回调

POST /studio/batches 也接受一个可选的 callback_url。同样适用已签名回调验证。事件包括 batch.updated、batch.completed、batch.paused 和 batch.cancelled,并带有稳定的 event_id、batch_id、batch_revision、observed_at、state_token、计数和点数总计。请读取 GET /studio/batches/{batch_id} 获取当前分页结果。事件包含紧凑快照,而不是会过期的下载 URL;工作线程两次轮询之间的中间变化可能会被合并。

投递是持久的,并且独立于生成过程重试。请按 event_id 去重,并容忍事件乱序;重复投递会保留相同请求体。接收端缓慢或失败不会创建新的生成,也不会阻塞生成队列。取消后,当已准入的工作完成时,可能还会发出进一步更新。后续显式请求的重启或返工会重新激活监控。Webhook 是一种 HTTP 集成,本身不会唤醒已结束的浏览器聊天。

批次响应包含 state_token,它会在有意义的进度或控制变化时发生变化,而仅签名 URL 续期时保持稳定。MCP 还额外提供 wait_studio_batch,用于活动会话期间在服务端进行有界等待;请参阅 MCP monitoring。

14

错误和限制#

错误统一使用一种结构:

json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Allowed values: 5, 10.",
    "field": "parameters.duration"
  }
}

HTTP 400/422 表示输入或参数无效;401 表示密钥无效/已撤销;402 表示点数不足;403 表示模型被禁用或访问被拒绝;404 表示模型/文件/任务不可用;409 表示幂等性冲突或仍在校验中;429 表示速率/并发限制;500 表示内部错误;503 表示服务暂时不可用。错误代码包括 INVALID_API_KEY、INSUFFICIENT_CREDITS、MODEL_NOT_FOUND、MODEL_DISABLED、INVALID_INPUT、INVALID_PARAMETER、INVALID_MEDIA_URL、MEDIA_NOT_ACCESSIBLE、UNSUPPORTED_MEDIA_TYPE、MEDIA_TOO_LARGE、FILE_NOT_FOUND、FILE_ACCESS_DENIED、RATE_LIMIT_EXCEEDED、GENERATION_FAILED、GENERATION_SERVICE_ERROR 和 SERVICE_UNAVAILABLE。GENERATION_SERVICE_ERROR 表示已报告的模型服务内部错误;这并不意味着输入大小或参数无效。为避免泄露其他账户的文件信息,缺失和不可访问的文件 ID 共用同一个 404 响应。

Default limits are 120 requests per minute per key, 10 generation submissions per minute per account, and 3 concurrent accepted generations per account. Every HTTP 429 includes error.retryable and a positive integer error.retry_after_seconds; the HTTP Retry-After header uses the same value. Request-window errors also return reason: "request_rate_limit", the configured limit, and a public scope (key, generation, bulk, mcp-upload-link or mcp-upload), without internal account/key IDs. The retry delay is the rounded-up time remaining in the minute window, not always 60 seconds. MCP tool errors preserve these fields in their JSON even when HTTP headers are unavailable. Account contention uses its own reason: "account_busy" and one-second delay. Generation capacity is handled separately by the durable queue; wait for the accepted task rather than resubmitting it.

json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded. Retry after 18 seconds.",
    "reason": "request_rate_limit",
    "scope": "key",
    "limit": 120,
    "retryable": true,
    "retry_after_seconds": 18
  }
}

对于请求窗口内被拒的情况(任务创建前),请等待所示延迟,并复用相同的幂等键和参数。如果响应表明任务已经失败,则该任务已终结。即使生成已终结失败,这也不授权再次发起新的付费尝试。

15

Studio 批量生成(API 和 MCP)#

批量生成可通过 API 和 MCP 使用。Studio 界面中暂时还没有批量工作区。你可以在一次 JSON 请求中提交最多 300 个产品。每个条目都会创建一个独立的 Studio 工作流,拥有各自的任务、已保存的工作流/设置、结果和点数核算。产品导入和参考素材下载会在后台进行;某个无效条目会独立失败,其余条目会继续。

Studio、LAB、REST、MCP、Shopify 和头像生成共享一个持久化服务器队列,在此部署中的绝对上限为 10 个活动生成请求。等待生成结果会占用一个名额。生成完成后,即使其文件仍在保存中,也会释放该名额。普通请求优先于批量请求;批量会使用可用容量,但受管理员设置的全局批量限制和每账户限制约束。默认值为同时 2 个批量工作流,且每个账户 1 个。同一账户的多个批次共享该限制。即使没有打开浏览器或没有客户端轮询,处理也会继续。

创建批次

POST /api/v1/studio/batches — 返回 HTTP 202。请提供必需的 Idempotency-Key 请求头,长度为 1–200 个字符。网络中断后,请复用同一个键和完全相同的 JSON。相同键但请求体已更改时会返回 HTTP 409;一旦接受,重试绝不会创建第二个批次。

bash
curl "$V4V_BASE_URL/api/v1/studio/batches" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: autumn-catalogue-001' \
  --data '{
    "name": "Autumn catalogue",
    "max_credits": 600,
    "input": { "prompt": "Show three benefits of this product in a calm reveal" },
    "parameters": { "duration": 8, "aspect_ratio": "9:16", "quality": "720p" },
    "items": [
      { "sku": "MUG-01", "product_id": "0123456789abcdef01234567" },
      { "sku": "BAG-02", "product_url": "https://shop.example/products/bag?variant=blue" },
      {
        "sku": "LAMP-03",
        "input": {
          "product_name": "Desk lamp",
          "product_description": "Adjustable warm light",
          "product_images": ["https://shop.example/lamp.jpg"]
        },
        "parameters": { "style": "TV Spot" }
      }
    ]
  }'

请使用当前部署的 Studio 工作流所支持的时长、格式和质量,与 POST /api/v1/studio 的要求相同。示例中为三个 8 秒 720p 的 Omni 片段预算了 600 点数:3 × 180 = 540 点数,剩余 60 点数余量。三个 10 秒 720p 片段需要 675 点数;1080p 需要 990 点数;4K 需要 1,980 点数,且这些都未计入参考视频定价、额外步骤或重试。在选择批次预算前,请始终先针对精确输入获取当前估算。

字段含义
name必填批次名称,1–200 个字符
max_credits必填的正数点数预算;已消耗点数加活动预留永远不得超过该值
input、parameters可选共享 Studio 字段,名称与单个 Studio 请求相同
items必填数组,包含 1–300 个产品对象
items[].sku可选客户端引用,最多 200 个字符
items[].product_id可选的 Products 素材库 ID,必须归此账户所有
items[].product_url可选公开产品页面用于导入;会保留变体/查询参数,但 eBay 跟踪参数会被规范化
V4V / API reference · v1构建值得观看的内容。
reference_image_urls
reference_video_urls
first_frame_url
keyframe_urls
last_frame_url
script-in
voice_audio_urls
@voice_1
@voice_2
video
clips

以下为经批准的基础费率,单位是每秒消耗的 V4V 点数,未包含管理员覆盖或现有工作流调整。这些费率会被直接使用,不进行 USD 换算,也不添加零售加价:

模型720p,无视频720p,有视频1080p,无视频1080p,有视频
Standard Reference28.51742.525.5
Standard Keyframe28.5不可用42.5不可用
Flash Reference1711.3不可用不可用
Flash Keyframe17不可用不可用不可用

5 秒输出示例:

模型5 秒,无源视频5 秒,含最多 5 秒源视频
Standard Reference,720p142.5 点数170 点数
Standard Reference,1080p212.5 点数255 点数
Standard Keyframe,720p / 1080p142.5 / 212.5 点数不可用
Flash Reference,720p85 点数113 点数
Flash Keyframe,720p85 点数不可用

没有视频输入时,计费秒数等于输出秒数。有参考视频或视频元素时,计费秒数等于 max(total input video seconds, output seconds) + output seconds,并按对应的视频输入费率计费。例如,10 秒 1080p 的 Standard Reference 输出,如果输入总时长为 15 秒,则计费 25 秒,调整前为 637.5 点数。会保留小数点数;完整费用只会统一四舍五入一次,保留两位小数。若输入时长未知,为进行保守估算,会使用模型允许的最大输入时长;服务器会在扣费前校验实际源时长。请使用与生成相同的输入来请求当前报价。管理端可为每个节点分别设置分辨率/视频输入费率。较旧的 Kling 节点会保留其现有价格和设置。

json
{
  "model": "video.kling_v40_key",
  "input": {
    "prompt": "Move from @first_frame to @keyframe_1 and finish at @last_frame",
    "firstFrameUrl": "https://example.com/start.png",
    "keyframeUrls": [
      "https://example.com/middle.png"
    ],
    "lastFrameUrl": "https://example.com/end.png"
  },
  "parameters": {
    "duration": 5,
    "resolution": "1080p",
    "aspectRatio": "16:9"
  }
}

在 MCP 中配合 generate_lab 使用此请求体,在 HTTP 中则配合 POST /api/v1/lab。若要获取报价,请添加 "source": "lab",并在 MCP 中使用 estimate_generation,或在 HTTP 中使用 POST /api/v1/generation/quote。务必先通过 get_model 或 GET /api/v1/models/{id} 发现所选模型。标准的生成授权、余额检查、幂等 key、回调和失败退款规则同样适用。

credits_reserved
incomplete: true
asset_id
file_id
file_id
project_id

对于单个 LAB/工作室请求,当账户容量可用时,会预留预估点数。如果已达到配置的并发任务上限(默认 3),请求会返回同一个可持久化的排队任务,其中 credits_reserved、credits_estimated 为零,且 queue 包含 limit、retry_after_seconds: 5 和 estimated_start_at: null。工作进程会在无需再次提交的情况下接纳等待中的任务。当有空闲槽位时,它会以原子方式预留点数;若此时余额不足,任务会在 stage: "admission" 时失败,并安排其 webhook。网络错误后请复用原始幂等键;不要通过创建另一个任务来绕过等待。对于批量任务,每一项的预估仅会在该项被接纳启动时预留。生成收费会消耗该预留。失败生成的收费沿用现有退款路径;未使用的预留点数会在完成或失败时释放。部分失败的工作室工作流中,成功步骤仍保留其正常收费。discovery、轮询、文件查询、回调和回调重试均不产生生成费用。

GET /balance 返回当前可用点数。GET /usage 返回该账户最新的 100 条生成请求。Profile 会显示每个密钥的生命周期请求/生成次数和已结算点数,以及最近的任务历史。上传内容会保留在用户的 LAB 素材库中,并可在其中删除。

项目更新接受 project_name(会去除首尾空白,1–200 个字符)、folder_id,或两者同时提供。发送 {"folder_id":null} 可将项目移出文件夹。省略的字段保持不变。响应包含 project_id 和已更新字段。重命名和移动也会更新对应的 API 任务和 LAB 历史;排队中的任务在其项目创建后会保留这些组织信息。

文件夹名称会去除首尾空白,长度必须为 1–80 个字符,且在同一账户内唯一。创建时返回 HTTP 201;重命名时返回 200,两者都会返回上述文件夹字段。重命名会保留文件夹 ID 及其项目。重复名称会返回 409 FOLDER_NAME_CONFLICT;无效字段会返回 422 INVALID_INPUT;无法访问的项目或文件夹会返回 404 PROJECT_NOT_FOUND 或 FOLDER_NOT_FOUND。如果文件夹创建响应不确定,请在重试前先列出文件夹。

items[].input、items[].parameters条目级覆盖;优先级为 条目 → 批次 → Studio 默认值
test_count可选值 5;仅处理前五个条目,然后等待显式恢复

请在 input 中使用产品素材库 ID、产品页面 URL,或产品详情/图片。当同时提供产品 ID 和 URL 时,会使用素材库中的产品。调用方显式提供的输入字段会覆盖导入值。参考媒体会通过与单次 API 生成相同的服务复制到账户自有存储中。API 的产品页面导入使用带重定向校验的有界公开 HTTP 请求。eBay 商品链接还提供受保护的浏览器回退方案。商店仍可能拒绝导入或要求登录;此时请提供自有产品 ID 或准备好的产品数据/图片。请求体大小限制为 1 MiB。请发送 JSON 产品列表;CSV 文件上传不属于本次 API 发布范围。

响应包含 batch_id、status、total_items、max_credits、credits_used、credits_committed、计数以及第一页条目。初始接受时不会为整个批次预留任何点数。任务可能要到下一次工作线程轮询时才出现,因此已接受的条目起初可能有一个空的 attempts 数组。

进度和结果

  • GET /api/v1/studio/batches?offset=0&limit=50 列出此账户的批次。
  • GET /api/v1/studio/batches/{batch_id}?offset=0&limit=50 返回条目进度。分页按从零开始的条目索引进行,单页最大 100 条。
  • 每个条目都包含其 index、可选的 sku、状态和 attempts。一次尝试包含常规的 task_id、version、credits_used 和状态;已完成的尝试还会包含已签名结果 URL。
  • GET /api/v1/tasks/{task_id} 检索单次尝试并刷新其已签名结果链接。同一账户名下不同密钥之间仍适用普通任务归属规则。

带有 IMPORT_FAILED 的条目是在付费生成准入前失败的。已知情况下,其错误信息会指出被拦截的 eBay/安全页面,并建议重试或提供准备好的产品数据。PREPARATION_FAILED 表示导入后、生成准备阶段出现了意外失败;联系支持时请附上 task_id。校验/媒体错误会保留其具体代码。其他条目会继续。每次失败的尝试都是终结性的:resume 不会重试它。修正输入或部署修复后,请使用下方的 retry_failed 或 rework 在同一批次中创建新的尝试。重复使用原始创建键会返回原始批次;不会重新运行它。

DIRECTOR_REQUEST_FAILED means the AI Director's text-model request was rejected before it could produce a video brief. REFERENCE_MEDIA_UNAVAILABLE identifies an unreadable, unsupported or oversized Director reference image. Report the task_id to support; do not treat either error as a video-generation failure or automatically spend credits on another attempt. Saved account images are sent directly from storage to the Director as binary image inputs, so this stage does not need anonymous CDN access.

轮询频率不要高于每五秒一次。当批次中的所有条目都达到终结状态时,批次会报告 completed;由于完成状态中可能包含失败条目,请检查计数和各个错误。受五条样本限制而被暂挂的条目会报告 waiting_for_sample。当这些样本的尝试都落定后,样本会以 TEST_REVIEW_REQUIRED 暂停。

暂停、恢复、取消和增加预算

POST /api/v1/studio/batches/{batch_id}:

json
{
  "action": "pause"
}
json
{
  "action": "resume",
  "max_credits": 1000
}
json
{
  "action": "cancel"
}

暂停和取消会阻止未来启动。已经获准启动的尝试会保留其预留并正常完成。恢复会在样本处理后、余额充值后或预算增加后继续其余部分。预算只能增加。取消会停止其余条目。当请求的批次状态未变化时,这些控制是幂等的;已取消的批次不能 resume,但可以显式 restart 或 rework 终结条目。

重试失败项、返工条目或重启批次

请使用同一个 POST /api/v1/studio/batches/{batch_id} 端点。这些操作会创建新的、可能收费的尝试,并且每次有意执行操作时都需要一个新的 Idempotency-Key 请求头(1–200 个字符)。网络中断后,请复用该键和完全相同的 JSON。请求体变更时会返回 IDEMPOTENCY_CONFLICT。这些操作的键作用域限定在账户和批次内,并且与批次创建彼此独立。请求体大小限制为 1 MiB。

操作执行内容
retry_failed仅执行其最新尝试失败的条目。可选的 item_indexes 可用于选择其中一部分;省略则表示所有失败条目。
rework已选定的终态条目,包括成功或已取消的条目。必填的 items 条目必须精确标识一个从零开始的 index 或当前 task_id,并可附带可选的 product_id、product_url、input 或 parameters。
restart所有条目,包括成功的条目,都会发起一次新的尝试。请先等待已准入的工作完成。示例门槛将被移除。
bash
curl "$V4V_BASE_URL/api/v1/studio/batches/$BATCH_ID" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalogue-retry-1" \
  -d '{"action":"retry_failed","max_credits":800}'

若只想修正单个商品,而不重新生成已成功的条目:

json
{
  "action": "rework",
  "items": [
    {
      "index": 1,
      "product_url": "https://www.ebay.de/itm/227541601859",
      "input": {
        "prompt": "A slow close-up of the bag and its details."
      },
      "parameters": {
        "duration": 8
      }
    }
  ]
}

若要重做你不满意的结果,请从批次响应中复制其当前的 items[].task_id。你可以保留相同输入,也可以提供新的提示词:

json
{
  "action": "rework",
  "items": [
    {
      "task_id": "task_0123456789abcdef01234567"
    },
    {
      "task_id": "task_abcdef0123456789abcdef01",
      "input": {
        "prompt": "Slower close-up, softer lighting"
      }
    }
  ]
}

使用现有的批次 URL 和新的操作 Idempotency-Key。批次会返回到 running,所选条目会变为 queued,且它们顶层的 task_id/results/error 会被清空,直到新的尝试被实体化/完成。其他已完成条目保持不变。较早的输出仅保留在 attempts 历史中;使用方应显示 items[].results 作为当前结果。每个条目只允许填写 index 或 task_id 其中之一。外部/无关任务会返回 TASK_NOT_FOUND;来自已被替换版本的任务会返回 BATCH_ITEM_VERSION_CHANGED(409),因此过期选择不会在无提示的情况下重新运行较新的结果。即使所选任务后来变成历史任务,重放已接受的键仍然是安全的。

若要完整重跑,请使用新键发送 {"action":"restart"}。这三种操作都接受可选的全局操作级 input 和 parameters 变更,以及增加后的 max_credits。这些变更会合并到该条目之前的请求之上;条目级变更优先生效。更改 product_id 或 product_url 会清除之前的备选项。较早的请求快照和结果保持不变。后续重试会继承最近一次已接受的修正,并准备新的工作流。

所选尝试必须处于终态。BATCH_ITEMS_ACTIVE(409)表示工作仍在排队/已准入/处理中,或所选重试条目并未失败,或刚刚接受了另一项重试。若要完全重启,请取消待处理工作,并等待已准入的尝试完成。GENERATION_UNRESOLVED(409)会在较早的生成请求处于排队、运行、分发中或状态不确定时阻止重试;请先核对其结果。NO_FAILED_ITEMS(409)表示没有可重试的内容。重试和返工会显式启动处理,包括该批次中的其他待处理条目;除非 resume 或 restart 将其移除,否则现有的五条目示例门槛会被保留。

max_credits 仍然是累计上限:之前的扣费加上当前预留仍然计入其中。重试不会退还此前成功步骤的费用,也不会重置预算。不会为整个批次一次性预留。新版本使用相同的全局和每账户批量队列。API/MCP 点数日志会保留批次、条目和版本归属信息。

响应会在 items[].attempts 中保留每一次尝试,每次尝试都有各自的 task/project 和递增的 version(编号可以跳号)。items[].version、条目状态和 counts 描述的是最新的目标版本;新版本在其任务尚未实体化之前,初始也会报告为已排队。credits_used 包含所有版本。只有当每个条目的最新版本都处于终态时,批次才算完成。重放操作绝不会启动额外尝试。每个批次最多保留 100 次创建版本的操作和 8 MiB 的累计变更;满额时,BATCH_HISTORY_LIMIT(409)会要求创建新批次。

INSUFFICIENT_CREDITS 或 BUDGET_EXCEEDED 会暂停新的启动。向账户充值点数不会自动恢复批次:必须显式调用 resume。预算准入和账户预留在各自的 MongoDB 文档内以原子方式完成,因此并发 worker 无法超出批次预算,也无法对同一次尝试重复扣费。不需要 MongoDB 副本集。

状态查询超时并不能证明生成失败。若生成提交响应丢失,其槽位会继续占用以供后续核对;系统不会自动提交替代的付费请求。生成一旦成功,文件存储重试会复用现有的生成结果。对于被明确拒绝的限流提交,可以通过有界退避进行重试。已完成结果审核、版本批准、ZIP 导出以及更广泛的 #194 计划中的工作室批量 UI 不在此次 API 发布范围内;单独的签名下载仍可通过常规任务结果获取。

点数日志

管理员可以按 API 或 MCP 筛选点数日志。条目会包含 API 密钥名称/ID、task/project/job ID、生成来源,以及适用时的批量批次/条目/版本标记。绝不会记录密钥明文。

预留和结算是 credit delta 为零的审计事件;元数据会记录预留金额。扣费和退款会且仅会一次性携带实际的 credit delta。balanceAfter 是账户可用余额,不包含尚未完成的预留。历史 API 扣费会根据已存储的任务回执进行恢复,不会再次向账户扣费;若无法重建历史可用余额,管理界面会明确说明。

失败生成诊断

失败的 REST 任务、MCP get_task 结果和带签名的 task.failed 回调共享同一个错误对象。message 是 V4V 摘要;provider_error 保留模型服务的原因,同时对凭据、私有路由和网络位置进行了脱敏。provider 使用公开路由别名 managed。

json
{
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Generation failed. Unused credits and failed generation charges have been released.",
    "stage": "generation",
    "retryable": false,
    "provider": "managed",
    "provider_error": "The model is currently unable to process speech edits. If you think this was an error, send feedback.",
    "hint": "Remove speech from the reference video or use still images."
  }
}

安全拒绝、语音编辑以及不支持的时长/分辨率需要修改请求。限流和超时包含 retryable: true、retry_after_seconds: 60 和恢复提示。未知原因会原样保留,不会编造诊断或重试建议。若不存在模型服务诊断,这些字段将被省略。较早的失败任务会得到补充增强,同时其工作流失败记录仍然可用。工作室和实验室会显示相同的脱敏原因,并将其作为 GA4 generation_failed.reason 发送(受现有 120 字符分析限制约束)。

恢复提示绝不会启动另一次生成。新的付费尝试必须由用户明确发起,并使用新的幂等键。现有的点数结算、失败步骤退款、已完成步骤扣费和 webhook 签名机制继续有效。