AiBatchItem ai.batch-item@1
Generated at from
openvibe-contracts v0.419.0 and
openvibe-sdk v0.161.0.
- Version
- 1.0.0
- Owner
- ai
- Visibility
- first-party
- Status
- active
- Compatibility
- backward
- Schema
https://openvibe.network/contracts/ai/batch-item.v1.json
ai.batch-item@1: one prompt of a batch on OpenVibe.AI (POST /api/v1/batches). The item is the queue and the status of that one prompt: it waits for capacity (or for a provider's own batch API), runs, and carries the answer, the run it made and the money. A prompt that reached its deadline without capacity expires and is never charged.
Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
idx | integer | yes | The item's place in the batch. |
|
status | enum | yes | queued (asked for, not started), waiting (no cheap capacity yet), running (a provider works on it), succeeded, failed, expired (the deadline passed; not charged), cancelled (the batch was cancelled). |
|
model | string | null | yes | The model the item asked for, or the batch's own. | |
run_id | string | null | yes | The run the item made, when it made one. |
|
answer | string | null | yes | The answer the provider gave, as text. | |
error_code | string | null | yes | ||
error_detail | string | null | yes | ||
reason | string | null | yes | The plain note about the prompt: it expired (it was not charged), it was cancelled before it ran (it was not charged), or it was already sent to the provider (it finishes and is charged). | |
capacity | string | null | yes | Where the answer came from: a community offer, the regular capacity, or a provider's own batch API. | |
route_provider | string | null | yes | ||
route_model | string | null | yes | ||
cost_nano_usd | string | null | What the answer really cost, in nano-USD (1 USD = 1e9 nano), as a string: the money is never a float. | ||
absorbed_nano_usd | string | null | What the network absorbed (the route cost more than the customer paid), in nano-USD, as a string. | ||
charged_nano_usd | string | null | What the customer was charged, in nano-USD, as a string: half the retail card. | ||
deadline_at | string | yes |
| |
created_at | string | yes |
| |
updated_at | string | yes |
|
Examples
From the contract's own test fixtures: valid ones validate, rejected ones must fail.
Valid: one-item
{
"idx": 0,
"status": "succeeded",
"model": "gpt-4o-mini",
"run_id": "run_01K6R3A1B2C3D4E5F6G7H8J9KF",
"answer": "A digest of the week.",
"error_code": null,
"error_detail": null,
"reason": null,
"capacity": "regular",
"route_provider": "openai",
"route_model": "gpt-4o-mini",
"cost_nano_usd": "1200",
"absorbed_nano_usd": "0",
"charged_nano_usd": "600",
"deadline_at": "2026-11-08T22:58:00.000Z",
"created_at": "2026-11-07T22:58:00.000Z",
"updated_at": "2026-11-08T00:10:00.000Z"
}Rejected: no-idx
{
"status": "succeeded",
"model": "gpt-4o-mini",
"run_id": "run_01K6R3A1B2C3D4E5F6G7H8J9KF",
"answer": "A digest of the week.",
"error_code": null,
"error_detail": null,
"reason": null,
"capacity": "regular",
"route_provider": "openai",
"route_model": "gpt-4o-mini",
"cost_nano_usd": "1200",
"absorbed_nano_usd": "0",
"charged_nano_usd": "600",
"deadline_at": "2026-11-08T22:58:00.000Z",
"created_at": "2026-11-07T22:58:00.000Z",
"updated_at": "2026-11-08T00:10:00.000Z"
}Rejected: unknown-status
{
"idx": 0,
"status": "later",
"model": "gpt-4o-mini",
"run_id": "run_01K6R3A1B2C3D4E5F6G7H8J9KF",
"answer": "A digest of the week.",
"error_code": null,
"error_detail": null,
"reason": null,
"capacity": "regular",
"route_provider": "openai",
"route_model": "gpt-4o-mini",
"cost_nano_usd": "1200",
"absorbed_nano_usd": "0",
"charged_nano_usd": "600",
"deadline_at": "2026-11-08T22:58:00.000Z",
"created_at": "2026-11-07T22:58:00.000Z",
"updated_at": "2026-11-08T00:10:00.000Z"
}Validate
const contracts = require('openvibe-contracts');
contracts.validate('ai.batch-item@1', value); // { valid, errors: [{ path, message }] }