API protocol
POST · Image generation
Direct answerPOST /v1/images/generations. Authentication, parameters, examples in three languages, result validation and error handling.
Updated · Reviewed
OpenFox · Image generation
POST https://api.openfox.vip/v1/images/generations
Model ID: YOUR_MODEL_ID
Authentication
Authorization: Bearer $OPENFOX_API_KEY
Create a model API key in API Keys. Dashboard sessions and personal access tokens are not model API credentials.
Keep credentials in environment variables on your server. Do not paste real keys, cookies or account records into this guide.
Request parameters
- model (body, string, Required): Exact model ID allowed by the API key.
- prompt (body, string, Required): Image description.
- n (body, integer, Optional): Gateway cap is 128, not a model capability. Omitted or top-level zero resolves to one; providers may impose smaller limits.
- size (body, string, Optional): Model and channel specific. No universal size enum.
- quality (body, string, Optional): Model and channel specific.
- response_format (body, string, Optional): URL or Base64 support depends on the channel.
- stream (body, boolean, Optional): Only supported by some models and channels.
- watermark (body, boolean, Optional): Provider-specific watermark control.
- generationConfig (body, object, Optional): See schema details.
- style (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- user (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- extra_fields (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- background (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- moderation (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- output_format (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- output_compression (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- partial_images (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- images (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- mask (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- input_fidelity (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- watermark_enabled (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- user_id (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
- image (body, provider-specific, Optional): Raw provider extension; type and support must be checked against the selected model and adapter.
Example values are not server defaults. Model-specific parameter support must be confirmed for the selected channel.
Model and channel limitations
Size, quality, format and price tiers depend on the model and channel. No size or quality is forced by this example. URL recovery does not persist ordinary Base64 responses.
Request example
Run one language example only. Creation requests may be charged; do not run every example or retry automatically.
Set OPENFOX_REQUEST_ID from the original X-Request-Id when recovering images. Set OPENFOX_TASK_ID from a real task creation response when querying tasks.
curl
# Bash / WSL; curl 7.76+ and jq. Run ONE language example, not all of them.
umask 077
RESULT=$(mktemp)
trap 'rm -f "$RESULT"' EXIT
: "${OPENFOX_API_KEY:?Set OPENFOX_API_KEY}"
curl --silent --show-error --fail-with-body --max-time 180 'https://api.openfox.vip/v1/images/generations' \
-H "Authorization: Bearer $OPENFOX_API_KEY" \
-H "Content-Type: application/json" \
--data-raw '{"model":"YOUR_MODEL_ID","prompt":"An orange cat beside a window in soft morning light."}' \
--output "$RESULT" || exit 1
jq -e 'type == "object" and (.error | not) and (.success != false) and (.code != false)' "$RESULT" >/dev/null || exit 1
# HTTP/business envelope checked only. Complete result validation is required:
# Require data[] with URL or Base64. Download or decode each image and verify its image format before saving. Never send this API key to external result URLs.
# Use the Python or JavaScript example in this guide for result processing.
python
# Python 3.10+; install: pip install httpx pillow
import asyncio, json, os
from urllib.parse import quote, urlparse
import httpx
async def main():
url = "https://api.openfox.vip/v1/images/generations"
headers = {}
headers["Authorization"] = "Bearer " + os.environ["OPENFOX_API_KEY"]
params = {}
async with httpx.AsyncClient(timeout=30, follow_redirects=False) as client:
async def read(target, method='GET', payload=None):
response = await client.request(method, target, headers=headers, params=params, json=payload)
response.raise_for_status()
value = response.json()
if not isinstance(value, dict) or value.get('error') or value.get('success') is False or value.get('code') is False:
raise RuntimeError('API business error')
return value
data = await read(url, "POST", json.loads("{\"model\":\"YOUR_MODEL_ID\",\"prompt\":\"An orange cat beside a window in soft morning light.\"}"))
import base64, io
from pathlib import Path
from PIL import Image
Image.MAX_IMAGE_PIXELS = 20_000_000
items = data.get('data')
if not isinstance(items, list) or not items:
raise RuntimeError('No images')
for index, item in enumerate(items):
if item.get('b64_json'):
if len(item['b64_json']) > 28_000_000:
raise RuntimeError('Image too large')
image_bytes = base64.b64decode(item['b64_json'], validate=True)
else:
asset = urlparse(item.get('url', ''))
if asset.scheme != 'https' or not asset.netloc or asset.username or asset.password:
raise RuntimeError('Unsafe image URL')
image_bytes = bytearray()
# Separate client: no API key, cookies or redirects.
async with httpx.AsyncClient(timeout=30, follow_redirects=False) as download_client:
async with download_client.stream('GET', asset.geturl()) as download:
download.raise_for_status()
async for chunk in download.aiter_bytes():
image_bytes.extend(chunk)
if len(image_bytes) > 20_000_000:
raise RuntimeError('Image too large')
if not image_bytes or len(image_bytes) > 20_000_000:
raise RuntimeError('Invalid image size')
with Image.open(io.BytesIO(image_bytes)) as image:
if image.width * image.height > 20_000_000:
raise RuntimeError('Image dimensions too large')
image.load()
image.save(Path('openfox-image-' + str(index) + '.png'))
print('Saved verified image', index)
async def bounded():
await asyncio.wait_for(main(), timeout=180)
asyncio.run(bounded())
javascript
// Node.js 20+; save as example.mjs and run: node example.mjs
// Install: npm install sharp
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 180000);
const signal = controller.signal;
try {
const url = new URL("https://api.openfox.vip/v1/images/generations");
const headers = {"Content-Type":"application/json"};
if (!process.env.OPENFOX_API_KEY) throw Error('Set OPENFOX_API_KEY');
headers["Authorization"] = "Bearer " + process.env.OPENFOX_API_KEY;
const read = async (target, method = 'GET', payload) => {
const response = await fetch(target, { method, headers, signal, redirect: 'error', body: payload === undefined ? undefined : JSON.stringify(payload) });
if (!response.ok) throw Error('HTTP ' + response.status);
const data = await response.json();
if (!data || typeof data !== 'object' || data.error || data.success === false || data.code === false) throw Error('API business error');
return data;
};
let data = await read(url, "POST", {
"model": "YOUR_MODEL_ID",
"prompt": "An orange cat beside a window in soft morning light."
});
if (!Array.isArray(data.data) || !data.data.length) throw Error('No images');
const { default: sharp } = await import('sharp');
const { writeFile } = await import('node:fs/promises');
for (const [index, item] of data.data.entries()) {
let bytes;
if (typeof item.b64_json === 'string' && item.b64_json.length) {
if (item.b64_json.length > 28_000_000 || !/^[A-Za-z0-9+/]*={0,2}$/.test(item.b64_json)) throw Error('Invalid or oversized Base64');
bytes = Buffer.from(item.b64_json, 'base64');
if (bytes.toString('base64').replace(/=+$/, '') !== item.b64_json.replace(/=+$/, '')) throw Error('Invalid Base64');
} else {
const asset = new URL(item.url);
if (asset.protocol !== 'https:' || asset.username || asset.password) throw Error('Unsafe image URL');
// Fresh request: NO Authorization header, cookies or redirects.
const download = await fetch(asset, { signal, redirect: 'error' });
if (!download.ok || !download.body) throw Error('Image download failed');
const chunks = []; let length = 0;
for await (const chunk of download.body) {
length += chunk.length;
if (length > 20_000_000) { controller.abort(); throw Error('Image too large'); }
chunks.push(chunk);
}
bytes = Buffer.concat(chunks);
}
if (!bytes.length || bytes.length > 20_000_000) throw Error('Invalid image size');
const image = sharp(bytes, { limitInputPixels: 20_000_000 });
await image.clone().raw().toBuffer(); // Decode actual pixels, not just HTTP or metadata.
await writeFile('openfox-image-' + index + '.png', await image.png().toBuffer());
console.log('Saved verified image', index);
}
} finally { clearTimeout(timer); }
Results and success criteria
Require data[] with URL or Base64. Download or decode each image and verify its image format before saving. Never send this API key to external result URLs.
Error handling
Check both HTTP status and business errors. A timeout does not prove the operation failed. Do not automatically retry creation requests; inspect the original request or usage first.
401/403: check credentials, scopes, model permissions and IP rules. 429: check quota and rate limits. 5xx: preserve a non-secret request ID and contact support.
Python and JavaScript share a 180-second network deadline. Read-only polling is bounded. Unknown or failure states stop the flow. Image decoding is local CPU work with byte and pixel limits.
Uploads, downloads and related endpoints
Only the image editing example uploads a local file. Set OPENFOX_IMAGE_PATH to a supported image. Other examples do not upload files. Download external results without platform credentials. Task artifacts require format-specific verification.
- https://api.openfox.vip/docs?operation=image-result
Full request schema
{
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"model",
"prompt"
],
"properties": {
"model": {
"type": "string",
"description": "Exact model ID allowed by the API key."
},
"prompt": {
"type": "string",
"description": "Image description."
},
"n": {
"type": "integer",
"minimum": 0,
"maximum": 128,
"description": "Gateway cap is 128, not a model capability. Omitted or top-level zero resolves to one; providers may impose smaller limits."
},
"size": {
"type": "string",
"description": "Model and channel specific. No universal size enum."
},
"quality": {
"type": "string",
"description": "Model and channel specific."
},
"response_format": {
"type": "string",
"description": "URL or Base64 support depends on the channel."
},
"stream": {
"type": "boolean",
"description": "Only supported by some models and channels."
},
"watermark": {
"type": "boolean",
"description": "Provider-specific watermark control."
},
"generationConfig": {
"type": "object",
"properties": {
"imageConfig": {
"type": "object",
"properties": {
"imageSize": {
"type": "string",
"maxLength": 64,
"description": "Provider resolution hint; not a guaranteed output dimension."
}
}
}
}
},
"style": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"user": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"extra_fields": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"background": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"moderation": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"output_format": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"output_compression": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"partial_images": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"images": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"mask": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"input_fidelity": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"watermark_enabled": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"user_id": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
},
"image": {
"description": "Raw provider extension; type and support must be checked against the selected model and adapter."
}
},
"additionalProperties": true
}
}
}
}
}
Sources and verification
docs/openapi/relay.json · relaykit/dto/openai_image.go · 2026-11-03
SHA-256: aeee6c35a35b2eaced964401f3826f369ad7ac8985c17989dcbbe08337d9fa01
source-reviewed; upstream-not-tested; source-reviewed; provider extensions conditional
Source review is not upstream business verification. Availability and billing depend on your account, group and channel.
Use cases
- getting-started
- troubleshooting
API protocols
/v1/images/generations
FAQ
Does this guarantee model availability?
No. Check the exact model, group and endpoint permissions in the marketplace.
Do examples include live credentials?
No. Set environment variables on your server and replace YOUR_MODEL_ID with an available exact model ID.
Should I retry immediately after a timeout?
Do not automatically retry creation requests. Check the request ID, task status and usage to avoid duplicate charges.
Related guides
Official sources
- OpenFox API Official