# Imagine 生图 / 生视频 API

RelayFlows Imagine 的接口路径和字段与 xAI 官方 Imagine API 一致,可以直接用 OpenAI / xAI SDK,把 base_url 换成我们的地址即可。

内测中

Imagine 目前处于内测阶段,尚未对所有账号开放:未开通的账号调用会返回 404 Imagine API 暂未开放。正式开放后无需修改代码即可直接使用。

结果只保留 24 小时

生成的图片 / 视频以及你上传的输入图,24 小时后自动删除。返回的下载链接是短期有效的签名链接;过期后重新 GET 一次任务就能拿到新链接。请在 24 小时内下载保存。

# 快速开始

Base URL:https://api.relayflows.com/xai/v1
鉴权:控制台 API 密钥里的个人密钥(sk-… 或 rf-…),放在 Authorization: Bearer <密钥>,也接受 x-api-key: <密钥>。团队密钥暂不支持。
计费:从账户余额扣费(美元),按实际交付结算;失败、被内容审核拦截的不扣费。每个任务的报价 / 实扣在响应的 estimated_cost_usd / cost_usd 字段里。

curl https://api.relayflows.com/xai/v1/images/generations \
  -H "Authorization: Bearer $RELAYFLOWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-image","prompt":"一只橘猫趴在窗台上晒太阳,胶片质感","n":1,"aspect_ratio":"1:1"}'

from openai import OpenAI

client = OpenAI(api_key="sk-...", base_url="https://api.relayflows.com/xai/v1")
img = client.images.generate(model="grok-imagine-image", prompt="一只橘猫趴在窗台上晒太阳", n=1)
print(img.data[0].url)

# 模型

model	用途
`grok-imagine-image`	文生图、图片编辑
`grok-imagine-video`	文生视频、图生视频、参考图生视频、视频延长

GET /models 返回当前可用模型。

# 图片生成 `POST /images/generations`

字段	说明
`prompt`	必填
`n`	1–4,默认 1
`quality`	不填 = Speed 档;`medium` / `high` = Quality 2.0 档(更高分辨率,单价不同)
`aspect_ratio`	Speed:`1:1` `2:3` `3:2` `9:16` `16:9`,`auto` = `1:1`<br>Quality:另支持 `4:3` `21:9` `5:2`,默认 `auto`
`response_format`	`url`(默认)或 `b64_json`
`deferred`	`true` 时立即返回 `202 {"request_id"}`,之后用 `GET /images/{request_id}` 取结果

同步模式最多等待约 50 秒,超时返回 202 {"request_id","status":"pending"},继续用 GET /images/{request_id} 取即可。n 大于 1 或网络较慢时建议直接用 deferred: true。

成功响应:

{
  "created": 1792607288,
  "request_id": "4bae743d-a702-4d07-a552-20f38c3c0204",
  "data": [
    { "url": "https://…", "mime_type": "image/jpeg", "file_id": "5b714f7a-bf9d-462e-97fa-8228f77af985" }
  ],
  "usage": { "cost_usd": 0.08 }
}

file_id 可以直接作为下一次编辑 / 图生视频的输入。

# 查询图片任务 `GET /images/{request_id}`

{ "request_id": "4bf342c6-…", "status": "pending" }

status 为 pending / done / failed。done 时带 data 和 usage(同上);failed 时带 error。支持 ?response_format=b64_json。

# 图片编辑 `POST /images/edits`

JSON 请求(不是 multipart):

{
  "model": "grok-imagine-image",
  "prompt": "把背景换成海边日落",
  "image": { "url": "data:image/jpeg;base64,/9j/4AAQ..." }
}

image 可以是 data URI(base64)、{"file_id": "..."},或本站之前返回给你的结果链接;多图编辑用 images: [...](1–5 张)
不支持外部图片 URL(出于安全原因服务端不抓取外部链接,会返回 400 unsupported_image_url),请先转成 data URI 或用 POST /files 上传
response_format、deferred 同图片生成;响应格式同图片生成

# 上传输入图 `POST /files`

multipart/form-data,字段 file。支持 jpg / png / webp / gif / bmp / tiff,≤ 20 MB,24 小时后删除。

curl https://api.relayflows.com/xai/v1/files \
  -H "Authorization: Bearer $RELAYFLOWS_API_KEY" \
  -F file=@photo.png

{ "id": "66e66963-2eba-477f-a8ce-6982d516b5da", "object": "file", "bytes": 139347, "filename": "photo.png",
  "mime_type": "image/png", "created_at": 1792607264, "expires_at": 1792693664, "purpose": "image" }

# 视频生成 `POST /videos/generations`(异步)

字段	说明
`prompt`	必填
`duration`	`6` / `10` / `15` 秒,默认 6(参考图模式只支持 6 / 10)
`resolution`	`480p`(默认)/ `720p` / `1080p`
`aspect_ratio`	`16:9` `9:16` `1:1` `2:3` `3:2`;默认文生视频 `16:9`,带图时 `2:3`
`image`	可选:首帧图 → 图生视频(格式同图片编辑的 `image`)
`reference_images`	可选:1–7 张参考图 → 参考图生视频(不能和 `image` 同时用)

{ "request_id": "cb6a7e8d-33d4-4b7b-b097-76a6da3c8583", "status": "pending", "estimated_cost_usd": 0.9 }

返回 202。轮询 GET /videos/{request_id},通常 20–90 秒完成,建议每 3–5 秒查一次:

{
  "request_id": "cb6a7e8d-33d4-4b7b-b097-76a6da3c8583",
  "status": "done",
  "model": "grok-imagine-video",
  "created_at": "2026-10-21T18:28:23.047Z",
  "expires_at": "2026-10-22T18:28:23.047Z",
  "cost_usd": 0.9,
  "video": { "url": "https://…", "file_id": "ff3e0b82-85ab-4a5c-a85e-004aaab8c387", "duration": 6.042, "width": 752, "height": 416 }
}

status 为 pending / done / failed(failed 时带 error)。

# 视频延长 `POST /videos/extensions`(异步)

{
  "model": "grok-imagine-video",
  "prompt": "镜头继续推近",
  "duration": 6,
  "video": { "request_id": "<之前视频任务的 request_id>" }
}

video 也可以写 {"file_id": "..."}(视频的 file_id)
duration:6 或 10 秒(按新增秒数计费)
只能延长本站 24 小时内生成的视频;输出是拼接好的完整视频,分辨率跟随原视频
返回 202 {"request_id","status","estimated_cost_usd"},同样用 GET /videos/{request_id} 轮询

# 预设模板(RelayFlows 扩展)

GET /imagine/templates:列出可用预设及其输入项 —— preset_inputs(选项)、aspect_inputs(比例)、text_inputs(文字)、image_inputs(图片)。每项有 id、label、required。
POST /imagine/templates/{id}/runs:

{
  "values": { "<preset/aspect/text 输入的 id>": "选项的 value 或文字" },
  "images": { "<image 输入的 id>": ["data:image/png;base64,..." , "<file_id>"] }
}

返回 202 {"run_id","status":"pending","estimated_cost_usd"}。

GET /imagine/runs/{run_id}:

{
  "run_id": "…", "template_id": "imagine-photo-edit", "status": "done", "cost_usd": 1.0,
  "outputs": [ { "type": "image", "url": "https://…", "file_id": "…", "width": 1024, "height": 1024, "mime_type": "image/jpeg" } ]
}

产物可能是多张图片、视频或二者混合(取决于预设)。

# 错误

格式与 OpenAI 一致:

{ "error": { "message": "n 只支持 1–4", "type": "invalid_request_error", "code": "invalid_request_error" } }

HTTP	`code` 示例	场景
400	`invalid_request_error`、`unsupported_image_url`	参数不合法、外部图片 URL
401	`invalid_api_key`、`api_key_paused`、`api_key_expired`	密钥缺失 / 无效 / 停用 / 过期
402	`insufficient_balance`(`type: insufficient_quota`)	余额不足
403	`team_key_unsupported`、`ip_not_whitelisted`	团队密钥、IP 不在白名单
404	`not_found`、`file_not_found`、`video_not_found`	`request_id` / `file_id` 不存在或已过期
422	`moderated`(`type: content_policy_violation`)	内容被审核拦截(不扣费)
429	`key_quota_exhausted`、`rate_limit_exceeded`	密钥配额或限速已满
503	`service_unavailable`	服务繁忙,请稍后重试

# 与 xAI 官方 API 的差异

项目	xAI 官方	RelayFlows
单次图片数 `n`	1–10	1–4
图片质量 `quality`	low / medium	不填 = Speed;`medium` / `high` = Quality 2.0
外部图片 URL 输入	支持	不支持(用 data URI / `file_id`)
视频时长	1–15 秒任意	6 / 10 / 15 秒
结果保留	官方 URL 时效不定	24 小时;链接短期有效,重新 GET 即可续签
预设模板	无	有(`/imagine/templates`)

# Imagine 生图 / 生视频 API

# 快速开始

# 模型

# 图片生成 POST /images/generations

# 查询图片任务 GET /images/{request_id}

# 图片编辑 POST /images/edits

# 上传输入图 POST /files

# 视频生成 POST /videos/generations(异步)

# 视频延长 POST /videos/extensions(异步)