# SDXL ControlNet Union · Image to Image API

> تحويل صورة إلى صورة باستخدام SDXL، مع توجيه متعدد من ControlNet عبر صور تحكم بالوضعية أو العمق أو الحواف أو التطبيع أو التقسيم

يحوّل صورة ابتدائية باستخدام أساس SDXL موجّه بمطالبة وصور تحكم اختيارية لـ openpose وdepth وteed وcanny وnormal وsegmentation. لكل إدخال تحكم مفتاح معالجة مسبقة خاص به. يعمل `strength` من 0.05 إلى 1، و`num_inference_steps` من 1 إلى 70، ويمكن إعادة ما يصل إلى 8 صور لكل استدعاء. يمكن توفير LoRAs وembeddings، ويكون الإخراج بصيغة jpeg أو png.

- Model id: `sdxl-controlnet-union/image-to-image`
- Made by: Stability AI
- Category: Image Editing
- Output: image
- Estimated price per run: $0.048 / image (cheapest run $0.048 (48 API credits))
- Run: `POST https://api.doitong.ru/v1/run/sdxl-controlnet-union/image-to-image`
- Quote: `POST https://api.doitong.ru/v1/quote/sdxl-controlnet-union/image-to-image`
- Docs page: https://doitong.com/ar/developers/models/sdxl-controlnet-union/image-to-image

## Pricing

Price: **$0.048 / image**. Estimated from the typical cost of one run, per output (`num_images`). The quote is exactly what the run charges.

The full example input below costs $0.048 = 48 API credits (1 image × 48 API credits).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.ru/v1/quote/sdxl-controlnet-union/image-to-image` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `prompt` |  | string | yes |  |  | صِف الصورة التي تريد توليدها بأكبر قدر ممكن من التفصيل للحصول على أفضل النتائج. |
| `controlnet_conditioning_scale` |  | number | no | `0.5` | 0 – 1 | قوة التهيئة المطبقة بواسطة ControlNet. |
| `image_url` | `image` | string (image URL) | yes |  |  | الصورة الابتدائية للتوليد، مقدّمة عبر عنوان URL. |
| `negative_prompt` |  | string | no | `` |  | موجّه سلبي يحدد تفاصيل الصورة غير المرغوبة. يمكنه استبعاد الألوان والعناصر والمشهد أو السمات والصفات الدقيقة، مثل الشارب أو الضبابية أو الدقة المنخفضة. |
| `image_size` |  | object {height, width} \| enum (string) \| null | no |  | `square_hd`, `square`, `portrait_4_3`, `portrait_16_9`, `landscape_4_3`, `landscape_16_9` | أبعاد المخرج، تُحدّد تلقائيًا من صورة التحكم عند عدم تقديم حجم. |
| `num_inference_steps` |  | integer | no | `35` | 1 – 70 | عدد خطوات الاستدلال المطلوب تنفيذها. |
| `guidance_scale` |  | number | no | `7.5` | 0 – 20 | قوة الالتزام بالموجّه لاختيار الصورة، معبَّر عنها بصيغة CFG (Classifier Free Guidance). |
| `strength` |  | number | no | `0.95` | 0.05 – 1 | درجة التشابه بين الصورة المُولّدة والصورة الابتدائية. |
| `seed` |  | integer \| null | no |  |  | بذرة لإعادة إنتاج الصور في Stable Diffusion. يمكن إعادة إنتاج الصورة تمامًا في كل تشغيل بالحفاظ على إصدار النموذج والموجّه والبذرة دون تغيير. |
| `num_images` | `num_outputs` | integer | no | `1` | 1 – 8 | عدد الصور المطلوب توليده. |
| `loras` |  | array of object {force, path, scale} | no | `[]` |  | أوزان LoRA المحددة للاستخدام، والمقدَّمة كقائمة. |
| `loras[].force` |  | boolean | no | `false` |  | ما إذا كان استخدام التضمين إلزاميًا: تجعل true الاستخدام إلزاميًا. |
| `loras[].path` |  | string | yes |  |  | مصدر وزن LoRA، يُقدَّم كمعرّف نموذج HF يُحيل إلى أوزان safetensors أو كملف safetensors يُحدَّد عبر عنوان URL أو مسار. |
| `loras[].scale` |  | number | no | `1` | 0 – 1 | المضاعف المطبق على وزن LoRA قبل دمجه في النموذج الأساسي. |
| `embeddings` |  | array of object {path, tokens} | no | `[]` |  | التضمينات المحددة للاستخدام، والمقدَّمة كقائمة. |
| `embeddings[].path` |  | string | yes |  |  | أوزان التضمين المحددة عبر عنوان URL أو مسار ملف. |
| `embeddings[].tokens` |  | array of string \| null | no |  |  | قائمة رموز التضمين، مع توفر تسمية تلقائية عند حذفها: يتلقى كل متجه في ملف التضمين رمزًا من التسلسل <s0> و<s1> ... . |
| `enable_safety_checker` |  | boolean | no | `true` |  | تنشيط مدقق السلامة؛ تُمكّن true الفحص. |
| `safety_checker_version` |  | enum (string) | no | `v1` | `v1`, `v2` | اختر بين مدقق أمان ViT مخصص (`v2`) ومدقق CompVis (`v1`، الافتراضي). |
| `expand_prompt` |  | boolean | no | `false` |  | توسيع الموجّه بموجّهات إضافية، ويُفعَّل عند كون القيمة true. |
| `format` |  | enum (string) | no | `jpeg` | `jpeg`, `png` | تنسيق ملف الصورة الناتجة. |
| `request_id` |  | string | no | `` |  | معرّف الطلب لربط الاستجابة بالطلب الذي أنشأها. |
| `preserve_aspect_ratio` |  | boolean | no | `false` |  | اضبطها على true للاحتفاظ بنسبة أبعاد الصورة المُولّدة حتى عندما يتجاوز حجمها الحد. للحصول على النسب الصحيحة عبر الاقتصاص بعد التوليد، اضبط crop_output على True. وتُقرّب قيم العرض أو الارتفاع غير القابلة للقسمة على 32 إلى أقرب مضاعف لـ 32، ولا يحافظ تغيير الحجم هذا على نسبة الأبعاد افتراضيًا. |
| `crop_output` |  | boolean | no | `false` |  | اقتصاص المخرج المُولّد إلى نسبة الأبعاد الصحيحة عند ضبط القيمة على true. |
| `openpose_image_url` |  | string (image URL) \| null | no |  |  | عنوان URL يشير إلى صورة التحكم. |
| `openpose_preprocess` |  | boolean | no | `true` |  | يتحكم في المعالجة المسبقة لصورة openpose. |
| `depth_image_url` |  | string (image URL) \| null | no |  |  | عنوان URL يشير إلى صورة التحكم. |
| `depth_preprocess` |  | boolean | no | `true` |  | يتحكم في المعالجة المسبقة لصورة العمق. |
| `teed_image_url` |  | string (image URL) \| null | no |  |  | عنوان URL يشير إلى صورة التحكم. |
| `teed_preprocess` |  | boolean | no | `true` |  | يتحكم في المعالجة المسبقة لصورة teed. |
| `canny_image_url` |  | string (image URL) \| null | no |  |  | عنوان URL يشير إلى صورة التحكم. |
| `canny_preprocess` |  | boolean | no | `true` |  | يتحكم في المعالجة المسبقة لصورة canny. |
| `normal_image_url` |  | string (image URL) \| null | no |  |  | عنوان URL يشير إلى صورة التحكم. |
| `normal_preprocess` |  | boolean | no | `true` |  | يتحكم في المعالجة المسبقة للصورة العادية. |
| `segmentation_image_url` |  | string (image URL) \| null | no |  |  | عنوان URL يشير إلى صورة التحكم. |
| `segmentation_preprocess` |  | boolean | no | `true` |  | يتحكم في المعالجة المسبقة لصورة التقسيم. |

File parameters (`image`, `openpose_image_url`, `depth_image_url`, `teed_image_url`, `canny_image_url`, `normal_image_url`, `segmentation_image_url`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "image": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

A fuller example:

```json
{
  "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.ru/v1/run/sdxl-controlnet-union/image-to-image?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.ru/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.ru/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/sdxl-controlnet-union/image-to-image?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/sdxl-controlnet-union/image-to-image", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.ru/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "sdxl-controlnet-union/image-to-image",
      "input": {
        "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
        "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "sdxl-controlnet-union/image-to-image",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 48,
    "usd": "0.048",
    "charged": 48,
    "refunded": 0
  },
  "input": {
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  },
  "output": {
    "images": [
      {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "width": 1024,
        "height": 768,
        "content_type": "image/jpeg"
      }
    ],
    "timings": {},
    "seed": 42,
    "has_nsfw_concepts": [
      false
    ],
    "prompt": "string"
  },
  "outputs": [
    {
      "type": "image",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "width": 1024,
      "height": 768,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `images` | array of object {url, width, height, content_type} | معلومات الملفات الخاصة بالصور المولّدة. |
| `timings` | object |  |
| `seed` | integer | بذرة توليد الصورة، بما في ذلك القيمة المختارة عشوائيًا إذا لم يتضمن المدخل بذرة؛ وإلا تكرر القيمة المقدمة. |
| `has_nsfw_concepts` | array of boolean | يشير إلى ما إذا كانت مفاهيم NSFW تظهر في الصور المُولّدة. |
| `prompt` | string | الموجّه المستخدم أثناء توليد الصورة. |

## Related models

- [SDXL ControlNet Union](https://doitong.com/developers/models/sdxl-controlnet-union.md) (`sdxl-controlnet-union`): $0.014 / image
- [SDXL ControlNet Union · Inpainting](https://doitong.com/developers/models/sdxl-controlnet-union/inpainting.md) (`sdxl-controlnet-union/inpainting`): $0.012 / image
- [FLUX.1 Kontext \[pro\]](https://doitong.com/developers/models/flux-pro/kontext.md) (`flux-pro/kontext`): $0.04 / image
- [GPT Image 2.5 Edit](https://doitong.com/developers/models/openai/gpt-image-2.5/flare/edit.md) (`openai/gpt-image-2.5/flare/edit`): from $0.12 / image
- [Nano Banana 2 Edit](https://doitong.com/developers/models/nano-banana-2/edit.md) (`nano-banana-2/edit`): from $0.06 / image
- [Nano Banana Pro Edit](https://doitong.com/developers/models/nano-banana-pro/edit.md) (`nano-banana-pro/edit`): from $0.15 / image
- [Qwen Image 3 Edit](https://doitong.com/developers/models/alibaba/qwen-image-3/edit.md) (`alibaba/qwen-image-3/edit`): from $0.04 / image
- [Seedream 5.0 Pro Edit](https://doitong.com/developers/models/bytedance/seedream/v5/pro/edit.md) (`bytedance/seedream/v5/pro/edit`): from $0.0675 / run of output image

## Links

- HTML page: https://doitong.com/developers/models/sdxl-controlnet-union/image-to-image
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=sdxl-controlnet-union/image-to-image
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.ru/v1/models/sdxl-controlnet-union/image-to-image