AiBatch ai.batch@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.v1.json
ai.batch@1: a batch of many prompts on OpenVibe.AI (POST /api/v1/batches, GET /api/v1/batches, GET /api/v1/batches/:id). The answers are not waited for: the batch is queued, and the batch says where it stands. A batch is billed at half the retail price through Billing like every other request; the batch table is the queue and the status, never a second ledger. The owner of the batch is the account that pays for it: a person, a developer app's project, or a first-party service with the ai.batches.create grant (the network's own account).
Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
id | string | yes |
| |
status | enum | yes | queued (asked for), running (items are being answered), succeeded, failed (an item failed), expired (the deadline passed with nothing answered), cancelled (the caller cancelled it and nothing is left in flight: a prompt that already has a run goes on and settles on its own path, and the batch keeps running). |
|
owner_type | enum | yes | Who pays for the batch. |
|
owner_id | string | yes | ||
project_id | string | null | yes | The developer app's project, when an app owns the batch. | |
item_count | integer | yes | How many prompts the batch carries. |
|
items | ai.batch-item | yes | The items, in order. The list of batches answers with the same objects and no items (an empty array): the items come from GET /api/v1/batches/:id. | |
discount | string | yes | The share of the retail card the customer is charged, as a decimal fraction of a million (500000 = half). | |
deadline_at | string | yes | When the batch stops waiting: the deadline the caller asked for (1 to 72 hours). |
|
created_at | string | yes |
| |
updated_at | string | yes |
| |
finished_at | string | null |
| ||
absorbed_nano_usd | string | null | What the network absorbed for this batch, in nano-USD, as a string. | ||
ran_on_regular_capacity | boolean | The batch ran on the ordinary capacity (not on free or community capacity): it cost the network more than the customer paid, and the difference is the absorbed amount. |
Examples
From the contract's own test fixtures: valid ones validate, rejected ones must fail.
Valid: a-queued-batch
{
"id": "bat_0123456789abcdef01234567",
"status": "queued",
"owner_type": "user",
"owner_id": "usr_01K6R3A1B2C3D4E5F6G7H8J9KF",
"project_id": null,
"item_count": 2,
"items": [],
"discount": "500000",
"deadline_at": "2026-11-08T22:58:00.000Z",
"created_at": "2026-11-07T22:58:00.000Z",
"updated_at": "2026-11-08T00:10:00.000Z",
"finished_at": null,
"absorbed_nano_usd": "0",
"ran_on_regular_capacity": false
}Valid: one-batch
{
"id": "bat_0123456789abcdef01234567",
"status": "succeeded",
"owner_type": "user",
"owner_id": "usr_01K6R3A1B2C3D4E5F6G7H8J9KF",
"project_id": null,
"item_count": 1,
"items": [
{
"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"
}
],
"discount": "500000",
"deadline_at": "2026-11-08T22:58:00.000Z",
"created_at": "2026-11-07T22:58:00.000Z",
"updated_at": "2026-11-08T00:10:00.000Z",
"finished_at": "2026-11-08T00:10:00.000Z",
"absorbed_nano_usd": "0",
"ran_on_regular_capacity": false
}Rejected: no-id
{
"status": "succeeded",
"owner_type": "user",
"owner_id": "usr_01K6R3A1B2C3D4E5F6G7H8J9KF",
"project_id": null,
"item_count": 1,
"items": [
{
"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"
}
],
"discount": "500000",
"deadline_at": "2026-11-08T22:58:00.000Z",
"created_at": "2026-11-07T22:58:00.000Z",
"updated_at": "2026-11-08T00:10:00.000Z",
"finished_at": "2026-11-08T00:10:00.000Z",
"absorbed_nano_usd": "0",
"ran_on_regular_capacity": false
}Rejected: unknown-status
{
"id": "bat_0123456789abcdef01234567",
"status": "whenever",
"owner_type": "user",
"owner_id": "usr_01K6R3A1B2C3D4E5F6G7H8J9KF",
"project_id": null,
"item_count": 1,
"items": [
{
"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"
}
],
"discount": "500000",
"deadline_at": "2026-11-08T22:58:00.000Z",
"created_at": "2026-11-07T22:58:00.000Z",
"updated_at": "2026-11-08T00:10:00.000Z",
"finished_at": "2026-11-08T00:10:00.000Z",
"absorbed_nano_usd": "0",
"ran_on_regular_capacity": false
}Validate
const contracts = require('openvibe-contracts');
contracts.validate('ai.batch@1', value); // { valid, errors: [{ path, message }] }