**Cost**: Model-priced per successful call. See the Credit Matrix for `image_reframe` model and resolution prices.

Image Reframe supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://openapi.codia.ai/v2/open/image/reframe' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png' \
  -F 'resolution=1024x1024'
```

Outpaint / extend an image to fill a larger canvas at a specified target resolution — generate new pixels on the outside of the original frame rather than scaling it up. Synchronous.

## What this API is for

Converting square assets to wide banner formats, extending portraits into landscape, repurposing a 1:1 product photo as a 16:9 hero image. Different from `upscale` (which adds pixels *inside* the same crop) — `reframe` adds pixels *outside* it.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source. |
| `resolution` | yes | Requested target dimensions as `WIDTHxHEIGHT`, e.g. `1920x1080`. Actual output dimensions may be adjusted to the sizes supported by the selected model. |
| `model` | no | Default `nano_banana_2`. Also: `nano_banana_pro`, `flux_3`, `ideogram_v3`. |

If `resolution` matches the source's aspect ratio, the result is effectively an upscale (use `upscale` instead). The endpoint shines when the **aspect ratio changes** and net new pixels need to be hallucinated.

## Response

Shared `ImageUrlListSuccess` — one URL.

## Billing & limits

- Credits follow the `image_reframe` model/resolution table in the global Credit Matrix.
- Synchronous.

## Errors

Standard set; `400` on malformed `resolution`.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_reframe` instead. Inputs and credit cost are identical.

مفتاح اختياري يحدده المستخدم (حتى 255 حرفًا). عند تعيينه، تُخزَّن الاستجابة الناجحة (2xx) مؤقتًا لمدة 7 أيام. إعادة المحاولة بالمفتاح نفسه + جسم طلب مطابق تُعيد الاستجابة المخزّنة (دون خصم رصيد إضافي)؛ أما إعادة المحاولة بالمفتاح نفسه مع جسم مختلف فتُعيد 409. استخدمه لجعل إعادة إرسال POST آمنة عند حدوث أعطال في الشبكة. في عمليات الرفع بصيغة multipart/form-data، تُقارن الطلبات بحسب حقول النموذج ومحتوى الملفات، لذا يُعاد تشغيل الرفع المُكرَّر حتى لو اختار العميل multipart boundary جديدًا.

Idempotency-Key

رابط URL العام للصورة المصدر المراد إعادة تأطيرها

image_url

الدقة المستهدفة بصيغة `WIDTHxHEIGHT`. ستُوسَّع الصورة لتملأ هذا الحجم. يقبل FLUX 2 Pro/Max أيضًا إعدادات الحجم المسبقة 1K/2K. تُقلَّص الطلبات التي تتجاوز الحد، بما فيها 4K، إلى نحو 4MP كحد أقصى (2048x2048 للصور المربعة)؛ ولا يُدعم إخراج 4K أصلي. تعتمد الفوترة على مساحة الإخراج بعد التعديل: ما يصل إجماليه إلى 1,048,576 بكسل يُحتسب بسعر 1K، وما يزيد على ذلك يُحتسب بسعر 2K.

resolution

النموذج الذي يُجري إعادة التأطير / التوسيع (outpaint). القيمة الافتراضية `nano_banana_2`. تتبع الأرصدة جدول النماذج/الدقة الخاص بـ `image_reframe`.

| النموذج | الافتراضي | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| `gpt_image` (medium) | 15 | 15 | 29 | 48 |
| `gpt_image_2_5` (medium) | 4 | 4 | 8 | 12 |
| `nano_banana_2` | 18 | 18 | 27 | 41 |
| `nano_banana_pro` | 36 | 36 | 36 | 65 |
| `seedream_5_pro` | 12 | 12 | 24 | - |
| `seedream_5_flash` | 5 | 5 | 5 | - |
| `seedream_5` | 10 | 10 | 10 | 10 |
| `seedream_4_5` | 11 | 11 | 11 | 11 |
| `flux_3` | 13 | 13 | 27 | 162 |
| `flux_2_pro` | 8 | 8 | 20 | - |
| `flux_2_max` | 19 | 19 | 43 | - |
| `ideogram_v3` | 16 | 16 | - | - |

تعرض صفوف GPT الجودة medium. أما مستويات الجودة الأخرى فتتبع GPT Image Credit Matrix المشتركة أعلاه.

model

مع `gpt_image` استخدم `low` أو `medium` أو `high` أو `auto`. ومع `gpt_image_2_5` (بما في ذلك Flare وSunburst) تُدعم أيضًا القيمتان `xhigh` و`max`. إذا لم تُحدَّد quality أو كانت `auto` فتُطبَّق فئة الفوترة medium. استخدم `resolution` لتحديد أبعاد الإخراج.

quality

image

حقل ملف الصورة المصدر للتوافق (مهمل: استخدم `image` بدلًا منه).

file

رابط URL للصورة المصدر عند عدم رفع صورة

روابط URL للصور المعالَجة

code

message

روابط URL للصور المُولَّدة أو المعالَجة

image_urls

data

جسم الطلب غير صالح أو تنقصه معاملات مطلوبة

مفتاح API مفقود أو غير صالح أو تم إبطاله

رصيد الحساب غير كافٍ أو انتهت صلاحية الاشتراك

لا يملك الحساب صلاحية الوصول إلى نقطة النهاية هذه

أُعيد استخدام Idempotency-Key مع جسم طلب مختلف.

تم تجاوز حد المعدل. انتظر عدد الثواني المحدد في الترويسة `Retry-After` قبل إعادة المحاولة.

حدث خطأ غير متوقع في الخادم

يوسّع الصورة إلى حجم أو نسبة أبعاد جديدة عبر توليد محتوى جديد خارج حوافها الأصلية.

إعادة تأطير الصورة

المدخلات

المخرجات

واجهات API ذات صلة