上传素材

POST/api/v1/uploads

生成任务的图片、视频、音频输入，都必须是存储在本服务上的文件。先在这里上传，再把返回的 url 填进模型对应的输入字段。之前任务生成结果的链接也可以直接使用，两者都可以通过列出你的文件查到。

上传的文件与工作室走同一套检查：图片和视频会经过内容审核，计入你的存储配额，并按套餐的保留期保存（见 expires_at）。免费套餐下，上传的文件先只保留几天；到期时如果已经用作过生成输入，会改为按套餐的完整保留期保存（这次检查完成后，下方列表里的 expires_at 才会显示延长后的时间）。多个文件未通过审核后，上传会被暂停一段时间（upload_suspended）。音频和视频的时长由服务端自己测量，按输入时长计费的模型以这个测量值为准。

请求

请求体直接放文件的原始字节（不是 multipart 表单）。

部分	说明
`Content-Type` 请求头 · 必填	文件的 MIME 类型，如 `image/png`、`video/mp4`、`audio/mpeg`。只接受图片、视频和音频类型，不接受 SVG。
`Content-Length` 请求头 · 必填	文件大小（字节），大多数 HTTP 客户端会自动设置。
`filename` 查询参数	可选的文件名，方便你自己对账。
`digest` 查询参数	可选，文件的 SHA-256，64 位小写十六进制。带上它重复上传同一个文件时，直接返回已有的链接，不会再存一份——适合批量任务。

curl "https://vidocraft.com/api/v1/uploads?filename=product.png" \
  -X POST \
  -H "Authorization: Bearer sk_test_xxxxxxxx" \
  -H "Content-Type: image/png" \
  --data-binary @product.png

响应

201 Created

{
  "url": "https://cdn.example.com/…/upload/image/9f86d08….png",
  "mime_type": "image/png",
  "size": 204813,
  "duration": null,
  "expires_at": "2026-10-22T10:36:31.248Z",
  "deduplicated": false
}

duration 是音频、视频的时长（秒），图片为 null。如果音频或视频返回 null，说明这个格式读不出时长；按输入时长计费的模型会以 media_unreadable 拒绝这个文件——请转换为 MP4、MOV、M4A、MP3、WAV、FLAC 或 OGG 后重新上传。
上传前可以先核对模型的限制：GET /api/v1/models 在每个素材参数的 media 里列出可接受的 MIME 类型、单文件大小上限、数量上限和时长范围。
测试密钥也会真实存储文件（沙箱生成同样要校验输入），所以两种模式下的上传都计入存储配额。

使用链接

把链接填进模型的素材参数。media.multiple: true 的参数接收链接列表；media.frames: true 的参数接收一个链接（作为首帧），或两个链接的列表 [首帧, 尾帧]。

{
  "model": "image-to-video:wzkmnjbjb3av",
  "input": {
    "image_urls": ["https://cdn.example.com/…/first.png", "https://cdn.example.com/…/last.png"],
    "multi_prompt": [{ "prompt": "the camera slowly pulls back", "duration": 5 }]
  }
}

不是本服务上的文件的链接，会以 media_not_uploaded 拒绝。唯一的例外是服务方批准直接引用的域名：这些域名下的 https 链接无需上传即可使用，其中的图片和视频会在提交生成时进行内容审核，被拒绝时返回 moderation_blocked。

列出你的文件

GET/api/v1/uploads

列出可以用作生成输入的文件——你上传的素材和之前任务的生成结果，按时间倒序。已删除和已过期的文件不会列出，并且只会返回这个 API 密钥所属账户自己的文件。

查询参数	说明
`type`	`image`、`video` 或 `audio`，不填则三种都列。
`source`	`upload`（你上传的文件）或 `generation`（任务生成结果），不填则都列。
`limit`	每页数量，1–100，默认 20。
`cursor`	上一页返回的 `next_cursor`。翻页过程中新增的文件会出现在最前面，不会打乱后面的页。

curl "https://vidocraft.com/api/v1/uploads?type=image&limit=2" \
  -H "Authorization: Bearer sk_test_xxxxxxxx"

{
  "files": [
    {
      "url": "https://cdn.example.com/…/upload/image/9f86d08….png",
      "type": "image",
      "source": "upload",
      "mime_type": "image/png",
      "size": 204813,
      "duration": null,
      "filename": "product.png",
      "task_id": null,
      "created_at": "2026-09-22T10:36:31.248Z",
      "expires_at": "2026-10-22T10:36:31.248Z"
    },
    {
      "url": "https://cdn.example.com/…/image/1b4f0e9….png",
      "type": "image",
      "source": "generation",
      "mime_type": "image/png",
      "size": 1830042,
      "duration": null,
      "filename": null,
      "task_id": "01J8Z…",
      "created_at": "2026-09-21T08:12:05.004Z",
      "expires_at": "2026-10-21T08:12:05.004Z"
    }
  ],
  "next_cursor": "MTc1ODQ0MjMyNTAwNDowMUo4Wi4uLg"
}

最后一页的 next_cursor 为 null。task_id 指向生成这个文件的任务。

请求

响应

使用链接

列出你的文件

本页目录