API 协议

GET · Recover image result

直接答案GET /v1/images/generations/result。包含鉴权、请求参数、三种语言示例、结果判定与错误处理。

更新 · 审核信息

OpenFox · Recover image result

GET https://api.openfox.vip/v1/images/generations/result

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

  • request_id (query, string, Required): X-Request-Id from the original image response. Not a task ID.

Example values are not server defaults. Model-specific parameter support must be confirmed for the selected channel.

Model and channel limitations

Use the original request ID and the same API key. Requires result storage to be enabled. Only persisted URL results can be recovered; retention is 12 hours.

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}"
: "${OPENFOX_REQUEST_ID:?Set the original request ID}"
curl --silent --show-error --fail-with-body --max-time 180 --get 'https://api.openfox.vip/v1/images/generations/result' \
  -H "Authorization: Bearer $OPENFOX_API_KEY" \
  --data-urlencode "request_id=$OPENFOX_REQUEST_ID" \
  --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:
# Poll processing within the shared 180-second deadline. Only succeeded with valid image data is success. Stop on failed, expired, unknown or unavailable; never regenerate automatically.
# 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/result"
    headers = {}
    headers["Authorization"] = "Bearer " + os.environ["OPENFOX_API_KEY"]
    params = {'request_id': os.environ['OPENFOX_REQUEST_ID']}
    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, "GET")
        for attempt in range(60):
            if data.get('status') not in ['processing']:
                break
            await asyncio.sleep(3)
            data = await read(url)
        if data.get('status') != 'succeeded':
            raise RuntimeError('Result not successful: ' + str(data.get('status')))


    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/result");
if (!process.env.OPENFOX_REQUEST_ID) throw Error('Set OPENFOX_REQUEST_ID from X-Request-Id');
url.searchParams.set('request_id', process.env.OPENFOX_REQUEST_ID);
const headers = {};
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, "GET");
for (let attempt = 0; data.status === 'processing'; attempt++) {
  if (attempt >= 59) throw Error('Polling limit reached');
  await new Promise(resolve => setTimeout(resolve, 3000));
  data = await read(url);
}
if (data.status !== 'succeeded') throw Error('Result not successful: ' + data.status);


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

Poll processing within the shared 180-second deadline. Only succeeded with valid image data is success. Stop on failed, expired, unknown or unavailable; never regenerate automatically.

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.

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.

Full request schema

{
  "parameters": [
    {
      "name": "request_id",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "pattern": "^[!-~]+$"
      },
      "description": "X-Request-Id from the original image response. Not a task ID."
    }
  ],
  "requestBody": null
}

Sources and verification

docs/openapi/relay.json · controller/image_result.go · 2026-11-03

SHA-256: aeee6c35a35b2eaced964401f3826f369ad7ac8985c17989dcbbe08337d9fa01

source-reviewed; upstream-not-tested; source-reviewed

Source review is not upstream business verification. Availability and billing depend on your account, group and channel.

适用场景

  • getting-started
  • troubleshooting

API 协议

  • /v1/images/generations/result

常见问题

这里是否保证模型可调用?

不保证。请在模型广场核对精确型号、账号分组与端点权限。

示例是否使用真实密钥?

不使用。请在自己的服务端设置环境变量,并将 YOUR_MODEL_ID 替换为可用的精确模型 ID。

接口超时可以立即重试吗?

创建请求不应自动重试。先核对请求编号、任务状态和用量,避免重复收费。

官方来源

  1. OpenFox API 官方