模型能力

引用文件作为输入

在任何 Imagine 端点接受公共 URL 或 base64 编码的图像/视频的地方，你都可以用 Files API 存储中的 file_id 替代。文件将从你的私有存储中在服务器端获取，因此：

• 无需带宽上传同一图像两次——对于迭代编辑循环非常有用。
• 原始文件保持私密（无需将其公开即可用作输入）。
• 适用于上传的文件和通过先前 Imagine 调用生成的资源（通过 storage_options）。

所引用的文件必须具有端点正确的内容类型（图像：PNG/JPEG/WebP；视频：MP4），并且必须已完全上传。

编辑存储的图像

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.image.sample(
    prompt="Add a party hat to the dog",
    model="grok-imagine-image-quality",
    image_file_id="file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a",  # instead of image_url
)

print(response.url)

curl -s -X POST https://api.x.ai/v1/images/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "Add a party hat to the dog",
    "image": { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" },
    "response_format": "url"
  }'

使用多个存储的图像进行编辑

response = client.image.sample(
    prompt="Blend these two scenes into one cohesive composition",
    model="grok-imagine-image-quality",
    image_file_ids=[
        "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a",
        "file_2cd998e7-bf12-44aa-92c8-e3d1f1c1234f",
    ],
)

# Each images entry independently carries url or file_id — mix kinds within a single request.
curl -s -X POST https://api.x.ai/v1/images/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "Blend these two scenes into one cohesive composition",
    "images": [
      { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" },
      { "url": "https://example.com/scene-b.jpg" }
    ],
    "response_format": "url"
  }'

从存储的第一帧生成视频

response = client.video.generate(
    prompt="Pan across the scene as the sky darkens",
    model="grok-imagine-video-1.5",
    duration=5,
    image_file_id="file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a",
)

print(response.url)

curl -s -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "Pan across the scene as the sky darkens",
    "duration": 5,
    "image": { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" }
  }'

编辑存储的视频

response = client.video.generate(
    prompt="Add rain and a moody atmosphere",
    model="grok-imagine-video",
    video_file_id="file_5be118c3-da55-31dd-76e7-a1b8c8d6355b",
)

curl -s -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Add rain and a moody atmosphere",
    "video": { "file_id": "file_5be118c3-da55-31dd-76e7-a1b8c8d6355b" }
  }'

使用多个存储的图像生成参考视频

response = client.video.generate(
    prompt="A woman in this dress walks down a city street at night",
    model="grok-imagine-video-1.5",
    duration=5,
    reference_image_file_ids=[
        "file_5be118c3-da55-31dd-76e7-a1b8c8d6355b",  # subject
        "file_2cd998e7-bf12-44aa-92c8-e3d1f1c1234f",  # outfit
    ],
)

# Each reference_images entry independently carries url or file_id — mix kinds within a single request.
curl -s -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A woman in this dress walks down a city street at night",
    "duration": 5,
    "reference_images": [
      { "file_id": "file_5be118c3-da55-31dd-76e7-a1b8c8d6355b" },
      { "url": "https://example.com/dress.jpg" }
    ]
  }'

相关

• Files API 集成 — 概览 + 顶点示例，同时展示输入和输出。
• 持久化生成的输出 — 输出方面：storage_options、公共 URL、过期语义。
• 管理文件 — 上传、列出、检索、更新和删除文件。