Image generation and editing API

The top-level model selects the connected GPT model that handles the Responses request. The image generator is a tool used by that model. An image generator does not need a separate entry in YoiYoi's /v1/models list or the member's Direct model allowlist. Use an active YoiYoi workspace API key whose owner can use the selected top-level model through the member's Direct model policy and the matching connected-provider entitlement.

This example uses codex/gpt-6-sol. If your enabled connected model is1moby/gpt-6-sol, replace only the top-level model value. Both prefixes use the same request shape; the connected account or upstream-selected image generator may differ.

curl -N -X POST "https://api.yoiyoi.xyz/v1/responses" \
  -H "Authorization: Bearer $CONFLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "codex/gpt-6-sol",
    "input": [{"role": "user", "content": [{"type": "input_text", "text": "Create a simple flat blue circle centered on a white background. No text."}]}],
    "store": false,
    "stream": true,
    "tools": [{"type": "image_generation", "quality": "low", "size": "1024x1024", "partial_images": 1}],
    "tool_choice": {"type": "image_generation"}
  }'

Find the completed image_generation_call item in response.completed.response.outputwhen stream is true. To receive one JSON response instead, setstream to false and partial_images to 0, then find the item in output. Either connected prefix can use either response mode. The item'sresult contains base64 image bytes; decode them using output_format. The requested size is not a guarantee of output dimensions: these canaries requested 1024×1024 and returned 1254×1254 PNGs. Streaming image events, including any partial image, are replayed after the connected provider finishes; they are not a real-time preview.

You may specify an image-tool model explicitly; gpt-image-2 was verified in earlier production canaries. When omitted, the upstream-selected image model is not reported. These October 13 calls used an internal signed Test principal; public Bearer-key and native Codex Desktop calls still need separate end-to-end confirmation. Image generation can consume connected-account quota.

Use POST /v1/images/generations for Text-to-Image and POST /v1/images/edits for Image-to-Image. Both routes call xAI Imagine directly; they do not invoke Grok Build, a chat endpoint, or a model tool call.

POST /v1/images/generations
POST /v1/images/edits

curl -X POST "https://api.yoiyoi.xyz/v1/images/generations"   -H "Authorization: Bearer $CONFLUX_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "xai/grok-imagine-image-2.0",
    "prompt": "A watercolor lighthouse at dawn",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "quality": "medium",
    "response_format": "url"
  }'

$headers = @{ Authorization = "Bearer $env:CONFLUX_API_KEY" }
$body = @{
  model = "xai/grok-imagine-image-2.0"
  prompt = "A watercolor lighthouse at dawn"
  resolution = "1k"
  quality = "low"
  response_format = "b64_json"
} | ConvertTo-Json

$result = Invoke-RestMethod -Method Post -Uri "https://api.yoiyoi.xyz/v1/images/generations" -Headers $headers -ContentType "application/json" -Body $body
$result.data[0].b64_json

URL responses are temporary. Copy or process the generated image promptly when it must be retained.

A single image accepts a public HTTPS URL, a base64 image data URI, or an xAI Files APIfile_id owned by the selected connected account.

curl -X POST "https://api.yoiyoi.xyz/v1/images/edits"   -H "Authorization: Bearer $CONFLUX_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "xai/grok-imagine-image-2.0",
    "prompt": "Render this as a detailed pencil sketch",
    "image": {
      "url": "https://example.com/source.png",
      "type": "image_url"
    },
    "resolution": "2k",
    "quality": "medium"
  }'

"image": { "url": "data:image/png;base64,..." }
"image": { "file_id": "file_..." }

For multi-image editing, replace image with images and send two to five entries. URL, data URI, and file_id entries may be mixed in one request.

"images": [
  { "url": "https://example.com/subject.png" },
  { "file_id": "file_style" }
]

• model must be xai/grok-imagine-image-2.0 and prompt is required.
• n supports 1 to 10 generated images.
• aspect_ratio supports auto, common portrait/landscape ratios, and xAI's wide 21:9 and 5:2 ratios.
• resolution supports 1k and 2k.
• quality supports auto, low, and medium.
• response_format supports url and b64_json.
• Image edits accept one image or two to five entries in images, but not both.

The response preserves xAI's exact usage.cost_in_usd_ticks value and also includesusage.cost_in_usd. One USD equals 10,000,000,000 ticks.

"usage": {
  "cost_in_usd_ticks": 400000000,
  "cost_in_usd": 0.04
}