curl https://v4v.ai/api/v1/models \
-H "Authorization: Bearer $V4V_API_KEY"身份验证
在“个人资料 → API 密钥”中创建一个具名密钥。API secret 和 webhook 签名 secret 出现时请保存;它们只显示一次。可以独立创建和撤销多个密钥。密钥 secret 以 SHA-256 哈希形式存储。
每个 API 请求都要发送 Authorization: Bearer v4v_live_…。请将此密钥保存在你的服务器上,不要放在浏览器应用或源代码管理中。撤销后会阻止未来请求;已接受的生成会继续执行。
基础 URL:https://v4v.ai/api/v1。
发现 LAB 模型
GET /models 列出当前 LAB 模型 ID、启用状态、输入、参数、默认值、条件和限制。GET /models/{model} 描述单个模型。ID 和 schema 来自与 LAB 相同的目录和默认值。Studio 配置是独立的。
下方示例中的模型名称均为实际目录 ID。请使用 discovery 查找你账户当前已启用的模型。字段名因模型而异:请保留 discovery 返回的名称,包括诸如 aspectRatio 或 referenceImageUrls 这样的 camelCase 名称。选择项的值是字符串;对于看起来像数字的选择项,也接受数值类型。字段可以放在 input 或 parameters 中,但不能同时出现在两者中。未知字段会被拒绝。带可选版本的模型会暴露 parameters.variant;请使用 discovery 返回的取值和默认值。
curl https://v4v.ai/api/v1/models \
-H "Authorization: Bearer $V4V_API_KEY"带时间轴的语音字幕
通过类型 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 工具将这些提示对齐到源片段的裁剪、速度和时间线位置。
最新生成模型
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-text | png、jpeg、webp、gif、svg |
gpt-image-2.6-sunburst-text | png、jpeg、webp、gif、svg |
gpt-image-2.6-flare-img | png、jpeg、webp |
gpt-image-2.6-sunburst-img | png、jpeg、webp |
gpt-image-2.6-economy-text | png、gif |
gpt-image-2.6-economy-img | png |
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 中读取当前价格、上线日期和费率调整。
Kling 4.0 视频模型
四个独立节点在实验室、工作流、API 和 MCP 中共享相同的生成与结果处理方式:
| 目录 ID | 模型 | 时长 | 分辨率 |
|---|---|---|---|
video.kling_v40_ref | Kling 4.0 Reference | 3–30 秒 | 720p / 1080p |
video.kling_v40_key | Kling 4.0 Keyframe | 3–30 秒 | 720p / 1080p |
video.kling_v40_flash_ref | Kling 4.0 Flash Reference | 3–20 秒 | 720p |
video.kling_v40_flash_key | Kling 4.0 Flash Keyframe | 3–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。
GPT-6 Astra 聊天
使用 GET /models/chat.gpt_6_astra 发现 chat.gpt_6_astra(slug:gpt-6-astra)。它的类型为 chat,并返回文本。discovery 包含 token 费率和取整规则。
{
"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} 和完成回调会直接返回内联文本,无需媒体文件:
{
"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 仍会计费。重复轮询或使用相同的幂等键重试,不会产生新的收费。
使用外部图片的实验室
媒体输入在同一字段中既接受外部 URL,也接受 V4V 文件 ID。数组中可以混用两者。URL 必须直接返回真实媒体文件,不能依赖浏览器 cookie 或交互式登录。建议使用 HTTPS 和有效期足够长的签名 URL。V4V 会在生成前验证并复制外部媒体;内部网络 URL 和不安全的重定向会被拒绝。
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"}}'上传私有媒体
POST /files 接受一个使用 multipart/form-data 的 file 字段。支持图片、视频和音频,但受模型限制。默认上传上限为 100 MiB,且还会受到部署的存储上传限制和代理限制的进一步约束。文件必须包含可解码的媒体;音频/视频检测要求服务器上安装 ffprobe。
curl https://v4v.ai/api/v1/files \
-H "Authorization: Bearer $V4V_API_KEY" \
-F 'file=@product.png'{
"id": "6aa962444bd1dd7ab65bc6b6",
"type": "image",
"content_type": "image/png",
"size": 123456
}请直接使用返回的 ID,不要加 file_ 前缀。GET /files/{id} 可在不消耗点数的情况下查询你文件的元数据。
{
"model": "ai.image_edit",
"input": {
"prompt": "Create a studio product photograph",
"referenceImageUrls": [
"6aa962444bd1dd7ab65bc6b6",
"https://example.com/side.jpg"
]
},
"parameters": {
"variant": "nano-banana-2"
}
}使用外部或私有媒体的工作室
POST /studio 使用与工作室 UI 相同的已选工作室工作流、预处理、模型执行、价格乘数和订阅折扣。
{
"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,但在工作室中不接受原始音频参考文件;不受支持的参考会返回验证错误。
任务和点数
生成在输入校验完成后返回 HTTP 202,并且在容量可用时完成点数预留;它不会等待生成完成:
{
"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 同级:
{
"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:
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。
{
"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 下载。任何持有结果链接的人都可在其过期前使用它。
重命名和整理项目
项目整理使用与 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。
# 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"}'幂等性
提交 LAB 或 Studio 请求时,请发送 Idempotency-Key(1–200 个字符)。相同账户、相同键值、相同端点和相同 JSON 内容会返回原始任务,即使该账户下使用的是不同 API 密钥也是如此。对象属性顺序会被忽略。对不同内容重复使用同一个键会返回 HTTP 409 IDEMPOTENCY_CONFLICT。如果原始请求仍在校验中,HTTP 409 REQUEST_IN_PROGRESS 会要求你使用相同键重试。被拒绝的提交仍会与其键关联;请使用新键修正后重新提交。
持久唯一索引可防止并发重试创建出另一条生成或预留记录。幂等性记录会随任务历史一起保留。
已签名回调
提供一个可选的公开 callback_url。V4V 会推送 task.completed 或 task.failed,其中包含任务字段、结果列表和稳定的 event_id。回调带有 X-V4V-Timestamp 和 X-V4V-Signature: v1=<hex> 请求头。请使用创建 API 密钥时显示的 webhook 签名密钥进行验证。
签名是对时间戳、一个字面量句点以及精确原始请求体计算得到的 HMAC-SHA256。请拒绝过期时间戳(例如超过五分钟),并以常量时间比较签名。
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。
错误和限制
错误统一使用一种结构:
{
"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.
{
"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
}
}对于请求窗口内被拒的情况(任务创建前),请等待所示延迟,并复用相同的幂等键和参数。如果响应表明任务已经失败,则该任务已终结。即使生成已终结失败,这也不授权再次发起新的付费尝试。
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;一旦接受,重试绝不会创建第二个批次。
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 跟踪参数会被规范化 |