# Images and vision

Choose the right model and endpoint for image generation or image understanding.

## Generate images

For models explicitly supporting this endpoint, send `POST /v1/images/generations`. First set `XINGSUAN_MODEL` to the full image model ID.



```bash
curl 'https://api.xsopc.com/v1/images/generations' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$XINGSUAN_MODEL",
  "prompt": "A glass pavilion in a forest, soft morning light",
  "n": 1
}
JSON
```



Support for `n`, size, quality and response formats varies. This is a minimal request; add any fields required by your selected model.

## Read the result

Some models return a URL or Base64 synchronously; others return a task ID. If you receive a task ID, query its state rather than treating the submission response as an image. Result URLs may expire; save results to your own storage promptly.

## Reference images and editing

`POST /v1/images/edits` applies only to models supporting editing. Acceptance of files, multiple files, Base64 or URLs depends on the endpoint and model. Not all image models support editing.

If the upstream requires URLs, supply your own accessible image link. Platform conversion from a local file depends on configured object storage and the model's upload adapter.

## Image understanding

Vision models can accept image content through chat messages. Replace the vision model ID and image URL in this body, then send it to `/v1/chat/completions`.



```json
{
  "model": "YOUR_VISION_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe this image."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://YOUR_MEDIA_DOMAIN/reference.png"
          }
        }
      ]
    }
  ]
}
```



A text-only model does not gain vision capability just because you provide an image link.

## Check billing units

Image generation may be billed by image, request or tokens. Vision input may be converted into billable tokens. Check the model details and usage records. Reference images can also incur input charges.