视频生成
简介
能力标识:video.generate · API 地址:https://api.anycap.io
本文档定义 Anycap 视频生成(能力标识 video.generate)对外的接口约定。所有接口与示例均使用生产地址 https://api.anycap.io。
统一接口(推荐)
新接入请用 POST /v1/generations + type=video。下面的 /v1/videos/generations 接口继续支持,用于兼容旧调用。
curl -X POST https://api.anycap.io/v1/generations \ -H "Authorization: Bearer $ANYCAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "video", "model": "<来自 GET /v1/generations/models?type=video 的模型>", "input": { "prompt": "一只橘猫在窗台上睡觉" }, "parameters": { "resolution": "720P", "ratio": "16:9" } }'input.prompt
input.image_url / input.last_frame_url
input.reference_*_file_ids
input.native_request
parameters
resolution、ratio、duration、audio。1. 接入准备
- 在控制台「Agent 接入」创建接入密钥,并授予所需视频档位权限。
- 所有请求使用
Authorization: Bearer <ANYCAP_API_KEY>与Content-Type: application/json;不要携带 Cookie、Origin 或浏览器会话,也不要复用浏览器登录态。 - 金额字段都是十进制整数字符串,按整数处理:1 积分 = 1000000 微积分,展示换算 1000 积分 = $1。
tier与model是二选一的两条路径,各有自己的查询接口:走档位——先查询GET /v1/videos/tiers,创建任务传tier;走模型——先查询GET /v1/videos/models,创建任务传model。不要编造来源 UUID、模型名或价格;规格以你所选路径的查询接口返回为准。
2. 接口一览
| 步骤 | 方法 | 路径 | 成功状态 |
|---|---|---|---|
| 档位发现 | GET | /v1/videos/tiers | 200 |
| 模型发现 | GET | /v1/videos/models | 200 |
| 创建视频任务 | POST | /v1/videos/generations | 202 |
| 查询任务 | GET | /v1/videos/generations/{id} | 200 |
| 查询并取结果链接 | GET | /v1/videos/generations/{id}?result=true | 200 |
| 取消尚未提交上游的排队任务 | DELETE | /v1/videos/generations/{id} | 200 |
要点:
- 创建接口在服务端完成报价与提交,调用方无需先单独获取报价。
- 对外仅提供
basic/standard/premium三个档位;每档背后的模型与规格由运营配置。档位即上限:不降级、不更换模型、不静默替换。 model与tier二选一:一个请求只传其中一个——tier来自GET /v1/videos/tiers,或model来自GET /v1/videos/models。都不传返回 400(field=tier);同时传时以model路由、tier只作约束。档位清单不透露背后的模型,档位与模型的对应关系也不对外提供。Idempotency-Key是你自己为同一逻辑调用保存的键:任意不透明字符串,最长 255 字节,按连接隔离;重复提交同一键返回原任务、不重复扣费。创建响应返回任务id(键本身是 UUID 时 id 与它相同)。- 所有路径均不带
/api前缀,仅接受 Bearer 接入密钥。
3. 创建任务参数(POST /v1/videos/generations)
请求头:
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <ANYCAP_API_KEY> |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 你的幂等键:任意不透明字符串(最长 255 字节;若为 UUID 则任务 id 与该键相同);优先级高于请求体 idempotency_key |
请求体(additionalProperties: false;未知字段返回 400):
modelstring模型优先模式必填(与 tier 二选一)
tier 二选一,传 model + prompt(或图片/素材输入)。必须是该密钥可调用的模型(从 GET /v1/videos/models 查询),绝不替换;用于 native_request 时同时也锁定模型tierstring档位优先模式必填(与 model 二选一)
model 二选一。basic / standard / premium。与 model 同时传时只起约束作用:模型不属于该档会返回 400(field=model)promptstring与图片/素材输入至少一个
max_prompt_charactersimage_urlstring否
last_frame_urlstring否
image_urlreference_image_urlsstring[]否
image_url,不放进参考图。wan3.0-video 的首/尾帧与参考图互斥,同一请求只能二选一reference_image_file_idsstring(uuid)[]否
reference_video_file_idsstring(uuid)[]否
reference_audio_file_idsstring(uuid)[]否
resolutionstring否
ratiostring否
durationinteger否
audioboolean否
idempotency_keystring否
resource_idstring(uuid)否(高级模式)
native_request 的来源。档位优先与模型优先请求会忽略它:平台在该密钥可用、已启用、已定价且能构建该请求的来源中选择native_requestobject否(高级模式)
规则:
- 两种选用方式,二选一,每个请求恰好传一个。 档位路径:先查询
GET /v1/videos/tiers,传tier+prompt(或图片/素材输入);模型路径:先查询GET /v1/videos/models,传model+prompt(或图片/素材输入)。两者都不传返回 400(field=tier)。其余字段都可省略,并在所选档位或模型自己的限额内解析。 model与tier同时传时,模型必须属于该档,否则返回 400(field=model)。该密钥无权调用的模型同样如此——绝不静默替换。- 省略 = 用该来源默认值;一旦指定就必须按指定值执行,超出该来源支持且已定价的范围直接 400,不会被替换成别的值。
- 素材输入决定谁能接单。 只有能构建请求里每一种输入类型的来源才会被选中:
wan3.0-video只接首帧image_url,Seedance 系列还可以接参考图、参考视频与参考音频。图片可以是公开 HTTPS 链接;视频和音频必须是 Anycap 自有上传(其秒数按输入秒计费)。 native_request是高级的「按协议原文」路径(见第 14 节):由所选模型的适配器校验、绝不跨协议改写,上面的字段不适用于它。
最小请求体(档位路径):
{ "tier": "standard", "prompt": "A small orange cat sleeping on a windowsill" }最小请求体(模型路径——用 model 替代 tier):
{ "model": "doubao-seedance-2-0-mini-260615", "prompt": "一只橘猫在窗台上睡觉" }4. 创建任务返回(202)
{ "id": "8f5b5b9e-1f2a-4c3d-9a1b-7c0f1d2e3a4b", "resource_id": "0f2a9c3e-4b5d-4e6f-8a9b-0c1d2e3f4a5b", "state": "queued", "error_code": "", "billing_status": "held", "reserved_microcredits": "191000000", "charged_microcredits": "0", "created_at": "2026-10-13T08:00:00Z", "selection": { "resource_id": "0f2a9c3e-4b5d-4e6f-8a9b-0c1d2e3f4a5b", "model": "<model>", "resolution": "720P", "ratio": "16:9", "duration": 5, "audio": true }}selection 仅在创建响应中返回,用于说明本次实际使用的模型、分辨率、比例、时长与音频。示例金额仅表示结构,实际金额以接口返回为准。
5. 档位发现:GET /v1/videos/tiers
该接口是档位路径的查询接口:只读返回当前密钥已授权、已启用且已定价的档位,创建任务时把这里返回的档位名传给 tier(与 model 二选一);不调用上游服务,也不创建预留。
完整返回字段:
{ "items": [ { "tier": "standard", "resolutions": [ { "resolution": "480P", "credits_per_second": "29", "minimum_credits": "116" }, { "resolution": "720P", "credits_per_second": "58", "minimum_credits": "232" } ], "ratios": ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9"], "min_duration": 4, "max_duration": 15, "max_prompt_characters": 1000, "default_resolution": "720P", "default_ratio": "16:9", "default_duration": 5, "audio": true } ]}金额仅为结构示例,实际以接口返回为准。
tier
basic / standard / premiumresolutions[]
credits_per_second(每秒积分)与 minimum_credits(该档最短可生成任务的积分)。价格按整积分发布,因此不暴露小数或微积分金额。档位内若含按 token 计量且发布了视频输入折扣的模型,还会带 with_video_credits_per_second(请求携带视频参考时自动适用)ratios[]
min_duration / max_duration
max_prompt_characters
frame_rate
input_types[]
text / image / video / audioconcurrency / requests_per_minute
default_resolution / default_ratio / default_duration / audio
该接口不返回档位背后的来源与模型;需要模型能力清单请使用下一节的模型查询接口。items 为空数组表示当前密钥没有可用档位,请检查来源启用、密钥权限与价目配置。
6. 模型查询:GET /v1/videos/models
只读查询,返回当前密钥可用(已授权、已启用且已定价)的每个模型及其自身参数与整积分价格。该接口不返回来源与档位,因此档位与模型的映射不会对外提供;档位视图仍是 GET /v1/videos/tiers。该接口是模型路径的查询接口:创建任务时传这里返回的 model(与 tier 二选一)。
完整返回字段:
{ "items": [ { "model": "doubao-seedance-2-0-mini-260615", "resolutions": [ { "resolution": "480P", "credits_per_second": "36", "with_video_credits_per_second": "22", "minimum_credits": "144" }, { "resolution": "720P", "credits_per_second": "77", "with_video_credits_per_second": "47", "minimum_credits": "308" } ], "ratios": [ "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" ], "min_duration": 4, "max_duration": 15, "max_prompt_characters": 1000, "frame_rate": 24, "input_types": [ "text", "image", "video", "audio" ], "concurrency": 10, "requests_per_minute": 600 } ]}model
model 直接创建任务,或作为 native_request.model 完全自控resolutions[]
credits_per_second 与 minimum_credits(该模型自己的最短任务积分,可以短于所属档位的最短时长)。按 token 计量且发布视频输入折扣的模型还带 with_video_credits_per_second(请求含视频参考时自动适用)ratios[]
min_duration / max_duration
max_prompt_characters
frame_rate
input_types[]
concurrency / requests_per_minute
note
- 该接口既可用于拼装高级
native_request(完全自控),也可用于模型优先创建:直接传model+prompt/resolution/ratio/duration/audio,平台在该模型自己的限额内解析。 - 一个模型一条记录:给出的是该模型自己的限额与价格,不是档位并集;档位视图(一档一价)仍在
GET /v1/videos/tiers。
7. 每个档位的限制
档位是唯一对外的维度:分辨率、比例、输出时长、提示词长度都由每个档位各自声明,且各不相同(有的档位只到 720P,有的可以到 1080P)。不应假设或硬编码,请以 GET /v1/videos/tiers 的返回为准:
- 某一档背后用哪个模型属于运营配置:调用方既不选择、也不能覆盖,平台不会因提示词或参数替换模型。
- 同档只有一个价格:一档背后有多个模型时,平台按成本最低优先选择执行,并在上游限流/额度不足时降级到下一个,因此实际由哪个模型生成不影响你付多少钱。
min_duration取平台下限(2 秒)与该档模型下限中的较大者,所以各档可能不同。- 档位优先模式的分辨率统一用大写(
480P/720P/1080P);高级native_request按所属模型族的写法(见第 14 节)。 - 请求该档不支持或未定价的分辨率、比例或时长一律返回 400,不会被降级、替换或改到别的档位。
模型路径是二选一的另一个选项:限额取 GET /v1/videos/models 中该模型自己的 resolutions、ratios、min_duration 与 max_duration,而不是档位的;计费按该模型已发布的每秒积分价。
8. 查询任务:GET /v1/videos/generations/{id}
- 路径参数
id:创建时返回的任务 id(当你的idempotency_key本身是 UUID 时,id 与它相同)。 video_url以原始&返回(不做 HTML 转义),可直接粘进浏览器;请复制完整链接(含全部查询参数)。- 这是上游服务的临时签名链接(约 24 小时)。平台不保存视频也不保存链接:在有效期内用
result=true重新获取,需要长期保存请及时下载。控制台结果区提供「复制链接 / 新标签页打开 / 下载」。 - 查询参数:可以不带,或只带
result=true(重新向上游查询并返回临时链接);result=false或其它参数一律 400。 - 只能查询属于本密钥的任务;非本密钥的任务返回 404。
完整返回字段(不带 result=true 时不含 video_url):
idstring(uuid)
resource_idstring(uuid)
statestring
queued / submitting / submitted / processing / finalizing / completed / failed / pendingerror_codestring
failure_reasonstring
duration_microsecondsstring
video_urlstring
result=true 且已完成时返回的上游临时 HTTPS 链接billing_statusstring
held / pending / settled / releasedreserved_microcreditsstring
charged_microcreditsstring
created_atstring(date-time)
不带 result=true 的查询只读本地任务状态:不重新生成、不重新扣费、不延长链接有效期。
创建返回里的 selection(第 4 节)GET 不重复返回;需要复现本次规格请以创建响应为准,或按所选路径读取限额:档位从 GET /v1/videos/tiers,模型从 GET /v1/videos/models。
9. 状态机、失败分类与轮询
| `state` | 处理方式 |
|---|---|
queued / submitting / submitted / processing / finalizing | 等待,每 15 秒查询一次本地任务 |
completed | 用 ?result=true 取 video_url |
failed | 明确失败,查看 error_code / failure_reason,预留已释放 |
pending | 待平台核对,保留任务 UUID,停止自动重提 |
billing_status:held(已预留)/ pending(待核对)/ settled(已结算)/ released(已释放)。
failure_reason 闭集(可能缺失;未知值按通用失败处理,不授权自动重提):
canceled、authentication_failed、service_access_denied、service_quota_exceeded、content_rejected、invalid_request、reference_preparation_failed、service_connection_failed、upstream_failed。
其中 canceled 由第 11 节的取消操作产生;authentication_failed 指生成服务认证失败(联系平台支持),不代表调用方的 Anycap 密钥无效。
10. 结果与有效期
- 结果是上游临时 HTTPS 链接,Anycap 不转存。
- 任务创建 24 小时后停止结果查询,返回
result_expired;临时不可用可能返回result_unavailable。 completed但没有video_url不代表没扣费;不要自动重新生成,也不要假设再次查询能延长有效期。
11. 取消:DELETE /v1/videos/generations/{id}
- 只取消尚未提交上游的排队任务,并精确释放一次预留。
- 可能已在途的任务返回 409,保留预留待核对。
- 返回被取消的任务对象(
state最终为failed,error_code=canceled)。
12. 调用示例
以下示例均使用生产地址。示例使用固定 UUID 以演示重放;生产环境应为每个业务操作生成新的 UUID,并在提交前持久化。
12.1 curl
export ANYCAP_API_KEY="<接入密钥>"export JOB_ID="8f5b5b9e-1f2a-4c3d-9a1b-7c0f1d2e3a4b" # 1) 查询可用档位curl -sS https://api.anycap.io/v1/videos/tiers \ -H "Authorization: Bearer $ANYCAP_API_KEY" # 1b) 模型路径:查询本密钥可调用的模型curl -sS https://api.anycap.io/v1/videos/models \ -H "Authorization: Bearer $ANYCAP_API_KEY" # 2) 创建视频任务(档位路径:tier 与 model 二选一)curl -sS -X POST https://api.anycap.io/v1/videos/generations \ -H "Authorization: Bearer $ANYCAP_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $JOB_ID" \ -d '{ "tier": "standard", "prompt": "A small orange cat sleeping on a windowsill", "resolution": "720P", "ratio": "16:9", "duration": 5, "audio": true }' # 2b) 模型路径:用 model 替代 tier(幂等键另取新值)curl -sS -X POST https://api.anycap.io/v1/videos/generations \ -H "Authorization: Bearer $ANYCAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<来自 GET /v1/videos/models 的模型>", "prompt": "一只橘猫在窗台上睡觉", "duration": 4 }' # 3) 查询任务curl -sS https://api.anycap.io/v1/videos/generations/$JOB_ID \ -H "Authorization: Bearer $ANYCAP_API_KEY" # 4) 完成后取结果链接curl -sS "https://api.anycap.io/v1/videos/generations/$JOB_ID?result=true" \ -H "Authorization: Bearer $ANYCAP_API_KEY" # 5) 取消尚未提交上游的排队任务curl -sS -X DELETE https://api.anycap.io/v1/videos/generations/$JOB_ID \ -H "Authorization: Bearer $ANYCAP_API_KEY"12.2 Go
package main import ( "bytes" "encoding/json" "fmt" "io" "net/http" "os" "time") const apiBase = "https://api.anycap.io" func main() { key := os.Getenv("ANYCAP_API_KEY") jobID := "8f5b5b9e-1f2a-4c3d-9a1b-7c0f1d2e3a4b" // 新的业务操作请用新的 uuid4 并先持久化 create := map[string]any{ "tier": "standard", "prompt": "A small orange cat sleeping on a windowsill", "resolution": "720P", "ratio": "16:9", "duration": 5, "audio": true, } body, _ := json.Marshal(create) req, _ := http.NewRequest(http.MethodPost, apiBase+"/v1/videos/generations", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+key) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", jobID) resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } raw, _ := io.ReadAll(resp.Body) resp.Body.Close() fmt.Println(resp.StatusCode, string(raw)) for i := 0; i < 120; i++ { job := get(key, apiBase+"/v1/videos/generations/"+jobID) fmt.Println("state:", job["state"], "billing:", job["billing_status"]) switch job["state"] { case "completed": fmt.Println(get(key, apiBase+"/v1/videos/generations/"+jobID+"?result=true")) return case "failed", "pending": fmt.Println("stop:", job["error_code"], job["failure_reason"]) return } time.Sleep(15 * time.Second) } fmt.Println("polling deadline; resume GET with the persisted UUID, never a new POST")} func get(key, url string) map[string]any { req, _ := http.NewRequest(http.MethodGet, url, nil) req.Header.Set("Authorization", "Bearer "+key) resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out := map[string]any{} json.NewDecoder(resp.Body).Decode(&out) return out}12.3 Java(Java 11+)
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.time.Duration; public class AnycapVideo { static final String API = "https://api.anycap.io"; public static void main(String[] args) throws Exception { HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build(); String key = System.getenv("ANYCAP_API_KEY"); String jobId = "8f5b5b9e-1f2a-4c3d-9a1b-7c0f1d2e3a4b"; // 新业务操作用新的 uuid4 并先持久化 String create = "{" + "\"tier\":\"standard\"," + "\"prompt\":\"A small orange cat sleeping on a windowsill\"," + "\"resolution\":\"720P\"," + "\"ratio\":\"16:9\"," + "\"duration\":5," + "\"audio\":true" + "}"; HttpRequest post = HttpRequest.newBuilder(URI.create(API + "/v1/videos/generations")) .header("Authorization", "Bearer " + key) .header("Content-Type", "application/json") .header("Idempotency-Key", jobId) .POST(HttpRequest.BodyPublishers.ofString(create)) .build(); System.out.println(http.send(post, HttpResponse.BodyHandlers.ofString())); for (int i = 0; i < 120; i++) { String body = http.send(get(key, API + "/v1/videos/generations/" + jobId), HttpResponse.BodyHandlers.ofString()).body(); System.out.println(body); if (body.contains("\"state\":\"completed\"")) { System.out.println(http.send(get(key, API + "/v1/videos/generations/" + jobId + "?result=true"), HttpResponse.BodyHandlers.ofString()).body()); return; } if (body.contains("\"state\":\"failed\"") || body.contains("\"state\":\"pending\"")) { return; } Thread.sleep(15000); } System.out.println("polling deadline; resume GET with the persisted UUID, never a new POST"); } static HttpRequest get(String key, String url) { return HttpRequest.newBuilder(URI.create(url)) .header("Authorization", "Bearer " + key) .GET() .build(); }}13. 参考素材
image_url(档位优先)以及native_request中的图片:公开 HTTPS URL,≤8192 字符,不含用户名密码、显式端口或 fragment;不接受本机/私网字面地址、HTTP 与 data URL。平台按原地址转发,由上游读取。- 私有素材使用
anycap-file://UUID(同空间、同成员、未过期)。自有上传走POST /v1/video-materials?kind=video|audio|image(见 13.1,接入密钥)或控制台浏览器会话;自有图片必须是 JPG / WebP / BMP(不接受 PNG)。外部 Agent 也可以使用公开 HTTPS 图片。 - 尾帧必须配首帧;首尾帧不与参考素材混用;图片≤10 张、视频≤5 段、音频≤5 段;视频/音频各自合计≤15 秒,输入视频 + 输出≤30 秒。服务端探测真实素材,不接受客户端声明时长。
13.1 上传自有素材:POST /v1/video-materials
先上传文件,生成请求里只带返回的文件 id。上传使用 multipart/form-data,只有一个 file 字段,类型用查询参数 kind=image|video|audio 指定;可选 Idempotency-Key 请求头让重复上传返回同一文件。服务端会用 ffprobe 探测真实格式、尺寸、帧率和时长,不接受客户端声明。
| kind | 格式 | 大小 | 说明 |
|---|---|---|---|
image | JPG、WebP、BMP | 20 MiB | 短边至少 240 px;不接受 PNG(参考图不保留透明通道) |
video | MP4、MOV(mov 容器) | 100 MiB | 作为参考时按真实秒数计入输入计费;参考视频合计最多 15 秒 |
audio | MP3、WAV | 15 MiB | 必须与至少一张图片或一段视频同时出现;参考音频合计最多 15 秒 |
返回(201):
{ "id": "11111111-1111-4111-8111-111111111111", "kind": "media", "filename": "reference.mp4", "bytes": 1234567, "created_at": "2026-10-30T08:00:00Z", "expires_at": "2026-11-02T08:00:00Z", "media": { "duration_microseconds": 5000000 }}curl -X POST "https://api.anycap.io/v1/video-materials?kind=video" \ -H "Authorization: Bearer $ANYCAP_API_KEY" \ -F "file=@./reference.mp4"- 生成时把 id 放进
reference_image_file_ids、reference_video_file_ids、reference_audio_file_ids;编辑接口使用video_file_id。 - 文件保留 72 小时,且归属同一工作空间与成员;其他密钥或成员不能使用该 id。
- id 稳定:重试提交复用同一个 id,不会重复上传或重复计费。上游拿不到 id;提交前平台会把它换成短期签名 URL。
- 图片仍可通过
reference_image_urls传公开 HTTPS 地址;视频与音频不允许公开 URL,因为要按秒计费。
14. 高级:直接指定模型
除了档位,你也可以直接指定模型(见 GET /v1/videos/models)。平台按该模型自己的默认值与限额构建请求,并按该模型在所选分辨率上的已发布价格计费。tier 可选:与 model 同时提交时只用于约束「该模型必须属于这个档位」,不匹配则返回 400 field=model(绝不静默替换);模型不存在或无权限同样如此。
{ "model": "doubao-seedance-2-0-mini-260615", "prompt": "一只橘猫在窗台上睡觉", "resolution": "720P", "ratio": "16:9", "duration": 5, "audio": true}只有 model 与 prompt(或 image_url)必填,其余字段可选、解析方式与档位请求一致。生效的是该模型自己的限额:例如 wan3.0-video 可以出 2 秒,即使它所在的 premium 档最短是 4 秒。响应同样带 selection,会写明实际使用的模型。
完全自控:native_request
POST /v1/videos/generations 也接受按所选模型写法提交的原生 native_request。native_request.model 必填,且必须是该密钥可调用的模型(见 GET /v1/videos/models,档位接口不会透露模型);tier/resource_id 可省略(仅凭 model 路由),一旦提供就必须指向同一个来源,否则返回 capability_unavailable。平台用该模型的适配器校验,绝不改写。prompt/image_url 等档位字段不生效。
Seedance 系列(doubao-seedance-*):
{ "tier": "standard", "native_request": { "model": "<model>", "content": [{ "type": "text", "text": "A small orange cat sleeping on a windowsill" }], "resolution": "720p", "ratio": "16:9", "duration": 5, "generate_audio": true }}字段:model(必填,取 GET /v1/videos/models 中该密钥可调用的模型)、content[](必填,text 或 image_url;图片可选 role first_frame / last_frame / reference_image)、resolution(小写)、ratio、duration(整数)、generate_audio、seed、watermark。
万相系列(wan3.0-*):
{ "resource_id": "0f2a9c3e-4b5d-4e6f-8a9b-0c1d2e3f4a5b", "native_request": { "model": "<model>", "input": { "prompt": "Animate the subject with gentle motion" }, "parameters": { "resolution": "480P", "ratio": "16:9", "duration": 5, "audio": true } }}字段:model、input.prompt / input.media[](first_frame / last_frame / reference_image / reference_video / reference_audio)、parameters(必填 resolution / ratio / duration,可选 audio / seed / prompt_extend / watermark)。
15. 错误与恢复
错误体统一为 {"error":{"code":"...","request_id":"..."}},并与 X-Request-ID 关联。
| HTTP | 含义 |
|---|---|
| 400 | 参数或素材错误;取值超出档位或模型限额;tier 与 model 都没传(field=tier);或 model 不属于所传 tier(field=model) |
| 401 | 密钥无效 |
| 402 | 余额不足 |
| 403 | 无该来源/档位权限 |
| 404 | 来源或任务不属于本密钥 |
| 409 | 报价/请求/幂等冲突;或任务已不可取消 |
| 429 | 并发或限速 |
| 503 | 没有匹配的可用来源或配置 |
恢复原则:
- 不要对所有错误统一重试。 400/401/403/404/409/402 应先修正再试。
- 超时、断网、5xx 或未收到任务响应都不能证明失败。先用已持久化的 UUID 查询;查询 404 也不证明上游从未收到,绝不能换新的 UUID 盲目重提。
- 查询(GET)可以有限退避重试;
pending等待平台核对。 - 本地轮询超时不取消任务、不释放预留、不授权新的付费生成。
16. 附:显式报价接口
旧的 /api/v1 两步接口仍然可用;新接入应使用第 2 节的统一接口。
| 步骤 | 方法 | 路径 |
|---|---|---|
| 报价 | POST | /api/v1/capabilities/video.generate/quotes |
| 提交 | POST | /api/v1/capabilities/video.generate/executions |
| 查询任务 | GET | /api/v1/video-executions/{id} |
报价返回 id、resource_id、price_version_id、usage_limits、amount_microcredits、expires_at;有效期 5 分钟。报价与原生请求绑定,改参数必须重新报价。
gemini-omni-1.2-flash-ext
将以下任一原生对象放入 native_request,外层 model 填相同模型,提交 POST /v1/videos/generations。所有模式的 prompt 均不能为空。分辨率为 360p、720p(默认)、1080p、4k,2160p 等价于 4k;比例为 16:9(默认)或 9:16。时长为 3–15 整秒(默认 10),首尾帧和续写为 3–10 秒;编辑不传 duration。首尾帧不能传 system_prompt 或 negative_prompt。参考图最多 10 张,支持公开 HTTPS 链接或自己上传的素材,不能与首尾帧或视频混用。编辑视频先通过视频素材接口上传,传入单个 anycap-file:// 引用(MP4/MOV/WebM,不超过 15 秒和 64 MB)。extend_from_task_id 使用当前空间内自己已完成、同模型且原通道仍可用的 Anycap 任务 UUID,不接受渠道任务 ID;也可将类型改为 edit 编辑旧任务。原片超过 15 秒须裁剪后上传。用 GET /v1/videos/generations/{id} 查询至完成,任务处理耗时不是成片时长。
文生视频
{ "model": "gemini-omni-1.2-flash-ext", "prompt": "The camera slowly pans across the scene.", "duration": 15, "aspect_ratio": "9:16"}首帧生视频
{ "model": "gemini-omni-1.2-flash-ext", "prompt": "The camera slowly pans across the scene.", "first_frame_image": "https://example.com/start.jpg", "duration": 6}首尾帧生视频
{ "model": "gemini-omni-1.2-flash-ext", "prompt": "The camera slowly pans across the scene.", "first_frame_image": "https://example.com/start.jpg", "last_frame_image": "https://example.com/end.jpg", "duration": 8}多图参考
{ "model": "gemini-omni-1.2-flash-ext", "prompt": "The camera slowly pans across the scene.", "image_urls": [ "https://example.com/cat.jpg", "https://example.com/ball.jpg" ], "duration": 8}编辑上传的视频
{ "model": "gemini-omni-1.2-flash-ext", "prompt": "The camera slowly pans across the scene.", "video_urls": [ "anycap-file://<uploaded-file-id>" ], "omni_reference_task_type": "edit"}续写上传的视频
{ "model": "gemini-omni-1.2-flash-ext", "prompt": "The camera slowly pans across the scene.", "video_urls": [ "anycap-file://<uploaded-file-id>" ], "omni_reference_task_type": "extend", "duration": 4}基于已有任务继续
{ "model": "gemini-omni-1.2-flash-ext", "prompt": "The camera slowly pans across the scene.", "extend_from_task_id": "<completed-anycap-job-uuid>", "omni_reference_task_type": "extend", "duration": 6}系统指令与反向提示词
{ "model": "gemini-omni-1.2-flash-ext", "prompt": "The camera slowly pans across the scene.", "system_prompt": "Render as a black-and-white silent film.", "negative_prompt": "people, cars, color", "duration": 6}已完成的视频任务可能返回 continuation:available 表示该视频能否继续编辑或续写;duration_microseconds 是完整成片时长(续写时包含原片),unavailable_reason 说明暂不可操作的原因。这些字段只读;实际编辑或续写仍通过 native_request.extend_from_task_id 传入已完成的 Anycap 任务 UUID。