ผลิตภัณฑ์แซนด์บ็อกซ์

ผลิตภัณฑ์แซนด์บ็อกซ์ คือ flow ที่รันได้แบบส่วนตัวซึ่งเป็นของโปรเจกต์เดียวเท่านั้น ประกอบด้วยสัญญา input/output ที่มีชื่อ บวกกับกราฟของ node ที่มีชนิดกำกับ เขียนขึ้นใน studio ของคอนโซลโดยไม่ต้องเขียนโค้ด node ของมันเรียกผลิตภัณฑ์ที่กำหนดให้โปรเจกต์นั้นอยู่แล้ว ผ่านเส้นทาง admission และการคิดเงินที่กำกับดูแลเดียวกันกับการเรียกใช้โดยตรง

ผลิตภัณฑ์แซนด์บ็อกซ์ไม่ใช่ผลิตภัณฑ์ที่เผยแพร่แล้ว: มันไม่เคยเข้าสู่แคตตาล็อกขององค์กรหรือแคตตาล็อกกลาง และ (เว้นแต่จะเข้ากันได้กับ chat) ไม่เคยปรากฏใน /v1/models การสร้าง บันทึก หรือรันมันไม่ได้เผยแพร่สิ่งใด

สัญญา#

สัญญาเป็นชุดย่อยของ JSON Schema: object ที่มี property ชนิด string, number, boolean หรือ object พร้อมรายการ required — ไม่มีการซ้อนชั้น ไม่มี combinator ไม่มี $ref การอ้างอิงภาพและเสียงเป็น property ชนิด object ที่มี format: "image" หรือ "audio" ฟิลด์ select คือ property ชนิด string ที่มี enum ของตัวเลือกที่ไม่ซ้ำกัน 1 ถึง 100 รายการ ค่าที่อยู่นอกรายการถูกปฏิเสธด้วย 422 input_type ก่อนมีค่าใช้จ่ายใด ๆ และสตริงว่างถือว่าไม่ได้ระบุค่า select อาจพก format: "voice", "aspect_ratio", "resolution" หรือ "duration" ได้ format เป็นเพียงคำอธิบายว่าตัวเลือกคืออะไร และไม่เปลี่ยนวิธีตรวจสอบค่าแต่อย่างใด

การอ่านและเขียนทุกครั้งต้องมีสิทธิ์ใช้งานโปรเจกต์อย่างชัดเจน (project.invoke — grant ระดับ Project Owner หรือ Consumer) การเป็นสมาชิกทีมเจ้าของและการเป็นผู้ดูแลองค์กรเข้าถึงผลิตภัณฑ์แซนด์บ็อกซ์ไม่ได้ และโปรเจกต์อื่นในองค์กรเดียวกันจะได้รับ 404 ไม่ใช่ 403

revision และการเปิดใช้งาน#

การบันทึกจะเขียน revision ใหม่ เสมอ; revision ที่บันทึกแล้วจะไม่ถูกแก้ไข การแก้ไขจึงเปลี่ยนการรันที่กำลังดำเนินอยู่ไม่ได้ การบันทึกอาจทำเครื่องหมายเป็น draft เพื่อเก็บการเชื่อมสายที่ยังไม่สมบูรณ์ไว้ และพก baseRevision ไว้สำหรับ optimistic concurrency — base ที่ล้าสมัยจะถูกปฏิเสธด้วย 409 revision_conflict

การเปิดใช้งาน แยกจากการบันทึก: มันตรวจสอบกราฟทั้งหมดอีกครั้ง สร้าง package ที่แก้ไขไม่ได้ (กราฟ สคีมา content digest เวอร์ชันของ runner และ dependency manifest ของ product id ที่กำหนดไว้) แล้ว deploy ผ่าน runtime adapter การเปิดใช้งานที่ล้มเหลวไม่เปลี่ยนอะไรเลย — revision ที่ใช้งานอยู่เดิมยังคงใช้งานอยู่

การเรียกผ่าน HTTP#

curl https://api.aigridapp.com/v1/sandbox/sbx-…/invoke \
  -H "Authorization: Bearer $AIGRID_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Accept: application/x-ndjson" \
  -d '{"input": {"question": "What does this error mean?"}}'

• โปรเจกต์คือโปรเจกต์ที่คีย์ผูกไว้; ผลิตภัณฑ์แซนด์บ็อกซ์ต้องเป็นของโปรเจกต์นั้น และ selector (X-AIGrid-Project และชื่อพ้อง) ทำได้เพียงระบุซ้ำให้ตรงกัน (มิฉะนั้นเป็น 403 project_mismatch และเป็น 404 สำหรับผลิตภัณฑ์ของโปรเจกต์อื่น)
• Idempotency-Key เป็นสิ่งจำเป็น ที่นี่ (8–128 อักขระ ต่างจาก chat ที่เป็นตัวเลือก) การใช้คีย์เดิมซ้ำจะเล่นการรันเดิมและค่าใช้จ่ายของมันเพียงครั้งเดียว
• body คือ {"input": {…}, "revision": n?} จากภายนอก มีเพียง revision ที่ deploy อยู่จริงเท่านั้นที่รัน — การระบุ revision อื่นเป็น 409 revision_not_active; ละ revision ไว้เพื่อใช้ revision ที่ใช้งานอยู่
• คำตอบคือระเบียนการทำงาน: สถานะ output ที่มีชนิดกำกับ ผลรายโหนด id ของการเรียกลูก และ chargedMicro การทำงานที่ Failed ก็ยังถูกส่งคืน พร้อมค่าใช้จ่ายที่เกิดขึ้นไปแล้ว

ภาพจะตอบกลับมาเป็นภาพ การเรียกด้วย bearer แบบธรรมดาที่ไม่ได้ระบุชนิดเนื้อหา — เช่น curl สั้น ๆ — จะได้ตัวภาพกลับมาเลย เมื่อการรันสำเร็จและค่า output เดียวคือภาพที่จัดเก็บไว้ โดยใช้ MIME type ของ asset นั้นเอง พร้อม Cache-Control: private, no-store, X-Content-Type-Options: nosniff และรองรับ range ส่วนกรณีอื่นยังตอบเป็นระเบียนการทำงานเหมือนเดิม — Accept: application/json, การรันแบบสตรีม NDJSON, การ execute จากคอนโซล, การรันที่ล้มเหลว หรือ output ที่ไม่ใช่ภาพเดียวพอดี การรันตัดบัญชีไปแล้ว จึงไม่มีการคิดเงินซ้ำไม่ว่าทางใด

ความคืบหน้าผ่าน NDJSON ส่ง Accept: application/x-ndjson เพื่อรับ event admitted, node และ complete ขณะกราฟทำงาน — ระเบียนของ node ที่เสร็จแล้วพก durationMs และพก remoteMs สำหรับการเรียกผู้ให้บริการ การปฏิเสธก่อน admission ยังคงเป็น HTTP error response ตามปกติ client ที่หลุดการเชื่อมต่อไม่ทำให้การรันค้าง: มันทำงานจนจบฝั่งเซิร์ฟเวอร์และตัดบัญชี

อินเทอร์เฟซ MCP#

MCP เป็นการเปิดใช้งานรายผลิตภัณฑ์แซนด์บ็อกซ์ และปิดอยู่โดยค่าเริ่มต้น (เปิดได้ใน studio หรือผ่าน console API) เมื่อเปิดแล้ว:

• /v1/sandbox/{id}/mcp พูดคุยด้วย transport แบบ stateless Streamable HTTP; GET/DELETE ตอบ 405 หลังการตรวจสอบสิทธิ์ ตามที่ transport นั้นกำหนด
• มันตรวจสอบ bearer key ชุดเดียวกันและใช้สิทธิ์ของโปรเจกต์เดียวกัน
• มันเปิดให้ใช้ tool เดียวคือ invoke_product ซึ่งสคีมา input/output มาจากสัญญาของ revision ที่ใช้งานอยู่และแก้ไขไม่ได้
• การเรียก tool ทุกครั้งต้องมี header Idempotency-Key; การลองใหม่ด้วยคีย์เดิมจะเล่นการรันเดิมและค่าใช้จ่ายลูกเดิมซ้ำ
• output มีทั้งค่าที่มีโครงสร้าง และเนื้อหาภาพ/เสียงแบบ native เมื่อสัญญาสร้างสิ่งเหล่านั้น

MCP ไม่ได้เพิ่มตัวตนหรือกระเป๋าเงินอีกชุด — มันคือเส้นทางการทำงานเดิมบนโปรโตคอลที่ต่างออกไป

การคิดเงิน#

ไม่มีค่าธรรมเนียมรวมของ parent node ที่มีค่าใช้จ่ายแต่ละตัว (node ชนิด product.chat หรือ media) ผ่านเส้นทาง admission, reservation, policy และ settlement เดียวกันกับการเรียกโดยตรง สร้างระเบียนการใช้งานของตัวเอง และคิดเงินจากกระเป๋าเงินของโปรเจกต์ ค่า chargedMicro ของการทำงานหนึ่งครั้งเท่ากับผลรวมของค่าใช้จ่ายลูกพอดี การเรียกลูกเป็น idempotent ต่อการทำงานหนึ่งครั้งและต่อ node การรันที่กลับมาทำต่อหรือถูกเล่นซ้ำจึงไม่คิดเงิน node ที่เสร็จแล้วสองครั้ง หากเงินหมดกลางคัน การทำงานจะล้มเหลวและรายงานค่าใช้จ่ายที่เกิดขึ้นไปแล้ว

media node#

ผู้ดูแลระบบเผยแพร่ผลิตภัณฑ์ภาพและเสียงพูดได้ พร้อมประกาศ capability descriptor (ชนิด อัตราส่วนภาพ เสียงพูด ความเร็ว การรองรับภาพอ้างอิง) และราคาต่อคำขอที่คงที่ media node ในแซนด์บ็อกซ์เรียกใช้ผ่านการเชื่อมต่อผู้ให้บริการของแพลตฟอร์มโดยใช้รูปแบบสายส่งของ OpenRouter สำหรับภาพและเสียงพูด; ไบต์ที่สร้างขึ้นถูกเก็บไว้เป็น asset ส่วนตัวของโปรเจกต์ ผลิตภัณฑ์ที่เป็นสื่ออย่างเดียวถูกเรียกผ่าน node ในแซนด์บ็อกซ์ ไม่ใช่ผ่าน chat completions — โดยใช้เส้นทาง reservation, settlement และการตรวจสอบเดียวกันในแต่ละ node

ขีดจำกัด#

ผลของ node ถูกบันทึกไว้หลังแต่ละ node เซิร์ฟเวอร์ที่เริ่มทำงานใหม่จึงทำต่อจากงานที่เสร็จแล้ว แทนที่จะคิดเงินซ้ำ

ถัดไป#

• การตรวจสอบตัวตน — คีย์ที่ endpoint เหล่านี้รับ
• ข้อผิดพลาด — รหัสการปฏิเสธข้างต้น รวมไว้ในตารางเดียว