Persist an Imagine output with a public URL

Set storage_options on any Imagine request to save the asset in Files. Set storage_options.public_url to also mint an unauthenticated URL on files-cdn.x.ai that lasts until you revoke it. filename is required.

The ephemeral imgen.x.ai / vidgen.x.ai URL is always returned. file_output.file_id is the stable copy. file_output.public_url appears only when you asked for one.

Generate, store, and share

curl -s -X POST https://api.x.ai/v1/images/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "A serene Japanese garden in winter",
    "response_format": "url",
    "storage_options": {
      "filename": "garden.jpg",
      "public_url": true
    }
  }'

Python:

import os
import xai_sdk

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

response = client.image.sample(
    prompt="A serene Japanese garden in winter",
    model="grok-imagine-image-quality",
    storage_options={"filename": "garden.jpg", "public_url": True},
)
print(response.url)                 # ephemeral
print(response.file_output.file_id) # file_...
print(response.public_url)          # files-cdn.x.ai

Expiry knobs are independent. storage_options.expires_after deletes the file (3600–2592000 seconds). storage_options.public_url.expires_after revokes the URL. Omit both and the file stays. A public URL cannot outlive its file.

Works the same on /v1/images/edits and the video endpoints. Video file_output lands on the completed poll response.

If public URL creation fails, the file can still be stored. Read public_url_error, then retry with client.files.create_public_url(file_id). Revoke later with POST /v1/files/{id}/public-url/revoke. Cap is 1,000 active public URLs per team.

Pitfalls

• Omit public_url and the file stays private. You can mint a URL later from the file_id.
• Hitting the 1,000-URL cap sets public_url_error without tearing down the stored file. Revoke unused links.
• Deleting the file also tears down its public URL.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.