خروجی ساخت‌یافته

استخراج فیلد

از یک متن یا تصویر (فاکتور، رسید، فرم) فیلدهایی با نوع مشخص بیرون بکشید؛ هر فیلد مقدار، اطمینان و در صورت نیافتن، مقدار null دارد.

POST/v1/extraction

شما فیلدهای مورد نظر را با نوع و توضیح می‌نویسید و متن (state) یا تصویر (images) را می‌دهید. پاسخ شیئی به نام answers است که کلیدش نام فیلد است و برای هر فیلد type، value و confidence دارد.

نکته‌ی مهم این است که value: null یعنی مدل مقدار را در منبع پیدا نکرده است. بعضی فیلدها فیلد guess هم دارند که فقط حدس مدل است؛ وقتی value برابر null است از guess به‌جای مقدار استفاده نکنید.

حداقل یکی از state یا images لازم است. تصویرها فقط به‌صورت data URL (data:image/png|jpeg|webp;base64,…) یا شیء { content_type, base64 } پذیرفته می‌شوند، تا چهار تصویر. نشانی اینترنتی تصویر دریافت نمی‌شود. fields یا شیئی از نام فیلد به تعریف آن است، یا آرایه‌ای از اشیایی که name دارند. سایر کلیدهای تعریف هر فیلد (مثل type، decimals، instructions) همان‌طور که نوشته‌اید به مدل می‌رسند و در این مسیر بررسی نمی‌شوند.

اگر مدل truncated را برگرداند، همان در پاسخ می‌آید. این مسیر استریم ندارد.

نمونه‌ها

curl https://1ai.ir/v1/extraction \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "cloudflare/clairic",
  "state": "Invoice INV-2291 from Novin Co., issued 2026-09-02, payable within 30 days. 4 pallets at $250 each plus $80 shipping.",
  "fields": {
    "invoice_number": {
      "type": "text"
    },
    "due_date": {
      "type": "date",
      "instructions": "Issue date plus the payment term"
    },
    "total": {
      "type": "number",
      "decimals": 2,
      "instructions": "Total including shipping"
    },
    "po_number": {
      "type": "text",
      "instructions": "Purchase order number"
    }
  },
  "reference_date": "2026-09-02"
}'
200پاسخ
{
  "model": "cloudflare/clairic",
  "answers": {
    "invoice_number": {
      "type": "text",
      "value": "INV-2291",
      "confidence": 0.99
    },
    "due_date": {
      "type": "date",
      "value": "2026-10-02",
      "confidence": 0.98
    },
    "total": {
      "type": "number",
      "value": 1080,
      "confidence": 0.99
    },
    "po_number": {
      "type": "text",
      "value": null,
      "guess": "INV-2291",
      "confidence": 0.97,
      "p_null": 1
    }
  },
  "truncated": false,
  "usage": {
    "input_tokens": 655,
    "output_tokens": 0,
    "total_tokens": 655
  }
}

بدنه‌ی درخواست

  • modelstringالزامی

    شناسه‌ی مدل استخراج.

  • statestring

    متنی که فیلدها از آن استخراج می‌شود، تا ۵۰۰٬۰۰۰ نویسه. اگر images ندهید الزامی است.

  • fieldsobject | arrayالزامی

    فیلدهای مورد نظر: شیء با کلید نام فیلد (حرف یا _ در آغاز، سپس حرف، رقم، _ . -، تا ۶۴ نویسه) یا آرایه‌ی ۱ تا ۵۰۰ تایی از اشیای دارای name. تعریف هر فیلد معمولاً type و در صورت نیاز instructions دارد.

  • imagesarray

    تا چهار تصویر PNG، JPEG یا WebP، به‌صورت data URL یا { content_type, base64 }. نشانی اینترنتی پذیرفته نمی‌شود.

  • reference_datestring

    تاریخ مرجع به شکل YYYY-MM-DD برای محاسبه‌ی تاریخ‌های نسبی.

  • optionsobject

    گزینه‌های اضافه برای مدل استخراج.

  • streamboolean

    فقط false پذیرفته می‌شود.

خطاها

  • invalid_request400

    بدنه معتبر نیست؛ مثلاً نه state نه images داده شده، fields خالی است، یا تصویر data URL نیست (param فیلد را می‌گوید).

  • model_kind_mismatch400

    مدل از دسته‌ی استخراج نیست.

  • insufficient_credits402

    اعتبار برای این درخواست کافی نیست.

  • model_not_found404

    مدل وجود ندارد یا به آن دسترسی ندارید.

صفحه‌های مرتبط