xai-grok-imagine-image

What it does

Operate xAI's first-party image API as a production system for image generation and editing via direct REST endpoints, focusing on production-grade workflow separation from video. It covers model selection among current image models, synchronous generation and editing, and handling of outputs, prompts, iteration, QA, cost and rate controls, privacy, safety, and rights review.

How it works

• Uses only documented endpoints:
  • POST https://api.x.ai/v1/images/generations
  • POST https://api.x.ai/v1/images/edits
  • Authorization: Bearer {XAI_API_KEY}
  • Content-Type: application/json
• Before launch, queries available models with a curl call to https://api.x.ai/v1/image-generation-models using a valid XAI_API_KEY.
• For text-to-image generation, sends a JSON payload including required fields: model and prompt, plus optional fields such as n, aspect_ratio, resolution, response_format, storage_options, user. It explicitly states that fields like seed, negative-prompt, guidance scale, mask, output-format selector, quality scalar, or streaming flag are not present in the current REST image schema.
• For natural-language image editing, uses POST to /v1/images/edits with payload including prompt, model, and exactly one of image or images, where each source includes url or file_id, mutually exclusive inside an object, and supports JPEG, PNG, WebP inputs. It notes that the OpenAI SDK's images.edit() is not compatible because it uses multipart form data, while xAI's edit route requires JSON.
• Explains response contents: data items may include url or b64_json, mime_type, file_output with file_id/filename, and storage status fields; usage cost is tracked via usage.cost_in_usd_ticks; describes four lifetimes for artifacts and security rules for handling URLs and storage.
• Provides an example (Python) that demonstrates a synchronous generation workflow with specific constraints, such as model usage, prompt structure, and base64 handling, including a dry-run setup and a paid-call gating mechanism.

When to use it

Use when you need production-grade image generation or editing via xAI Grok Imagine API, not Grok video or third-party gateways. This skill is intended for direct xAI image API integrations, and it emphasizes production-oriented workflows, model management, and output lifecycle control.

What it can touch

• The described REST endpoints and JSON payloads: POST /v1/images/generations, POST /v1/images/edits
• Authentication via Authorization: Bearer {XAI_API_KEY}
• Notes on model names and aliases such as grok-imagine-image-quality, grok-imagine-image, and retired grok-imagine-image-pro
• Output handling fields: data, url, b64_json, mime_type, file_output, public_url, storage_error, and usage
• CLI snippet to query models via curl

Caveats

• The skill warns to recheck model endpoints, console, pricing, rate limits, release notes, and legal terms before deployment.
• It mandates using a team-scoped API key with minimal ACLs and avoiding exposure in code or logs.
• It explicitly states that certain features are not present in the REST image schema (seed, negative-prompt, guidance scale, mask, streaming flag) and should not be invented.
• The Batch API is separate and has different constraints (e.g., 25 MB per-request payload limit is not evidence of the direct route limit).
• The content references cost estimates and provider claims, which should be validated against live contracts and pricing.