跳到主要内容

生成

一次生成按需产出一张图片、一段视频或一首歌，独立于任何对话。每种生成的用法相同：

  1. 发起。 响应为 202 Accepted，带上状态为 queued 的生成。
  2. 轮询：用 GET 读取，直到其 status 为 completed、failed 或 canceled。
  3. 取回 files。 completed 后，files 里就是结果，每个都带新的下载链接——从此它们就是终端用户自己的文件。
curl -s "$NEWEYES_API_BASE/v1/images/generations" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt": "A sunlit reading nook with a green armchair, watercolor style"}'
{
  "object": "image",
  "id": "a81b…",
  "type": "generate",
  "status": "queued",
  "files": [],
  "created_at": "2026-10-19T08:10:00Z",
  "completed_at": null
}
curl -s "$NEWEYES_API_BASE/v1/images/$IMAGE_ID" \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN"

状态与错误​

生成先是 queued，然后 running，最后以 completed、failed 或 canceled 结束；结束后不再变化。failed 的生成在 error.code 里说明原因：

error.code含义
content_blocked内容安全检查拒绝了这个请求或它的某个输入。
insufficient_credits项目余额已耗尽。
insufficient_available_credits项目的积分都被进行中的工作占用了。
invalid_input某个输入无法使用——例如视频比这个操作能处理的更长。
generation_failed没有产出结果。
timeout耗时过长。

图片和音乐每隔几秒轮询一次即可；视频可能需要几分钟，每 10 秒左右轮询一次。

图片​

接口作用
POST /v1/images/generations按 prompt（最多 4,000 个字符；要出现在图片里的文字请放在引号里）画一张图，可参考最多 8 张 reference_images。
POST /v1/images/edits按 prompt 编辑或合成 1 到 8 张 images，未提到的部分保持不变。用位置指代图片，例如"第一张图"。
GET /v1/images、GET /v1/images/{image_id}用户的图片生成，按从新到旧；单个生成。

视频​

接口作用
POST /v1/videos按 prompt 生成视频，可以从一张 first_frame 图片开始（并以 last_frame 结束）。
POST /v1/videos/edits按 prompt 修改一段 3 到 15 秒的 video 的局部——替换物体、改变风格、添加元素——保持其时长和镜头。
POST /v1/videos/remakes按 prompt 为 video 里的场景重新拍一条。
POST /v1/videos/motion-transfers让 image 里的人物按 video 里人物的动作动起来。
POST /v1/videos/reframes只改变视频的画幅（aspect_ratio）和分辨率（resolution），并延展画面填满新画幅。
POST /v1/videos/soundtracks用一段 audio 替换 video 原有的声音。
GET /v1/videos、GET /v1/videos/{video_id}用户的视频生成，按从新到旧；单个生成。
POST /v1/videos/{video_id}/cancel取消一个生成（见下）。

POST /v1/videos 的参数：

  • duration 为 4 到 12 秒（默认 5）；resolution 为 480p、720p（默认）或 1080p；aspect_ratio 为 16:9、4:3、1:1、3:4、9:16、21:9 或 auto（默认：跟随输入）；audio 让视频带声音（默认开启）。
  • quality: "pro" 支持最长 15 秒和 4k，并可使用参考素材：最多 9 张 reference_images、最多 3 段 reference_videos（合计最多 15 秒）、最多 3 段 reference_audios（需要至少一张参考图片或一段参考视频）。参考图片不能和 first_frame / last_frame 同时使用。

以源视频为输入的操作只使用较长视频中的一段：用 start_seconds 指定那一段的起点。不指定时，比操作所能处理的更长的源视频会以 invalid_input 失败。各操作的具体限制见 API 参考。

取消视频​

POST /v1/videos/{video_id}/cancel 取消一个生成。queued 的生成会立刻以 canceled 结束。已经在渲染的会被要求停止，并在结果确定前保持 running：之后以 canceled 结束——或者，如果视频先完成了，以 completed 结束，照常交付并计费。已经结束的生成原样返回。

音乐​

POST /v1/music 按 prompt 生成一首歌（MP3 文件）：主题、乐器、人声或歌词。genre、mood 和 tempo 可进一步细化。duration_seconds 只是参考：结果通常是一首两分钟左右的完整歌曲。

限制与计费​

  • 每个终端用户同时最多有三个未完成的生成，图片、视频和音乐合并计算。第四个会被拒绝，返回 429 rate_limited 并带 Retry-After。
  • 发起生成需要项目的计费账户有可用余额。生成在产出结果时计费；没有交付结果就结束的生成不计费。
  • 请带上 Idempotency-Key，这样重试永远不会发起第二个生成。
  • 输入是 POST /v1/files 返回的文件 id——或之前某次生成的文件。