GenVR API
Back to API Reference

Batch APIs

Send up to 10 jobs in one HTTP call using a requests array. The usual flow matches single-shot APIs: generate → status → response — each step has a batch endpoint on the same /v2 prefix.

Typical workflow

  1. 1

    POST /v2/generate-batch

    Start your jobs. Each item in requests is the same JSON you would send to POST /v2/generate. From the response, read each task's id from data.results[i].body.data.id (when that sub-call succeeded).

  2. 2

    POST /v2/status-batch

    Poll progress for many tasks at once. Each item matches POST /v2/status: include id, uid, category, and subcategory. Repeat until statuses show completion (or your app policy).

  3. 3

    POST /v2/response-batch

    Fetch outputs when ready. The request body is the same shape as status-batch (one object per task with id, uid, category, subcategory). Use the same id values you got from step 1.

Endpoints

POST/v2/generate-batch— per item: same body as /v2/generate
POST/v2/status-batch— per item: same body as /v2/status
POST/v2/response-batch— per item: same body as /v2/response

Request body (all three endpoints)

Every batch call uses Authorization: Bearer YOUR_TOKEN. The JSON body always has a single property: requests, an array of 1–10 objects. Examples below substitute your session or localStorage when set.

  • requests[0] is the first job, requests[1] the second, and so on. Order is preserved in data.results.
  • For generate-batch, each element is a full generate payload (e.g. uid, category, subcategory, prompt).
  • For status-batch and response-batch, each element uses the same fields as the single /v2/status or /v2/response call — typically id (from generate) plus uid, category, subcategory.
generate-batch — body shape
{
  "requests": [
    {
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev",
      "prompt": "a red apple on a table"
    },
    {
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev",
      "prompt": "a blue mug"
    }
  ]
}
status-batch and response-batch — same item shape (use task ids from generate)
{
  "requests": [
    {
      "id": "TASK_ID_FROM_GENERATE",
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev"
    },
    {
      "id": "ANOTHER_TASK_ID",
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev"
    }
  ]
}

Replace TASK_ID_FROM_GENERATE with the real id strings returned in the generate-batch response. Status and response batches can list the same tasks in the same order.

Batch response shape

HTTP 200 wraps one entry per input index. Each entry has an index, the HTTP status of that sub-call, and a body object (the same JSON you would get from the matching single endpoint). See Sample response under each endpoint in the Examples section for concrete JSON.

{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "status": 200,
        "body": {
          "success": true,
          "data": {
            "id": "...",
            "status": "..."
          }
        }
      },
      {
        "index": 1,
        "status": 200,
        "body": { }
      }
    ]
  }
}

Examples

Each endpoint has cURL, JavaScript (fetch), and Python (requests) tabs — install Python deps with pip install requests. Placeholders use your session or localStorage when set. For bash, multiline JSON after -d is fine. Run generate-batch first, then use the returned id values in status and response.

1. generate-batch

Creates tasks; read task ids from data.results[i].body.data.id for the next steps.

curl -X POST "https://api.genvrresearch.com/v2/generate-batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
  "requests": [
    {
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev",
      "prompt": "a red apple"
    },
    {
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev",
      "prompt": "a blue mug"
    }
  ]
}'
Sample response (HTTP 200)
{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "status": 200,
        "body": {
          "success": true,
          "data": {
            "id": "pred_7xK9mN2",
            "status": "queued"
          }
        }
      },
      {
        "index": 1,
        "status": 200,
        "body": {
          "success": true,
          "data": {
            "id": "pred_8yL0nO3",
            "status": "queued"
          }
        }
      }
    ]
  }
}

2. status-batch

Poll many tasks at once. Replace TASK_ID_FROM_GENERATE with ids from the generate-batch response.

curl -X POST "https://api.genvrresearch.com/v2/status-batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
  "requests": [
    {
      "id": "TASK_ID_FROM_GENERATE",
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev"
    },
    {
      "id": "ANOTHER_TASK_ID",
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev"
    }
  ]
}'
Sample response (HTTP 200)
{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "status": 200,
        "body": {
          "success": true,
          "data": {
            "id": "pred_7xK9mN2",
            "status": "processing"
          }
        }
      },
      {
        "index": 1,
        "status": 200,
        "body": {
          "success": true,
          "data": {
            "id": "pred_8yL0nO3",
            "status": "completed"
          }
        }
      }
    ]
  }
}

3. response-batch

Same request body as status-batch. Call when tasks are done (or per your polling rules). Output shape follows the single /v2/response contract for your model.

curl -X POST "https://api.genvrresearch.com/v2/response-batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
  "requests": [
    {
      "id": "TASK_ID_FROM_GENERATE",
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev"
    },
    {
      "id": "ANOTHER_TASK_ID",
      "uid": "YOUR_UID",
      "category": "imagegen",
      "subcategory": "flux2_dev"
    }
  ]
}'
Sample response (HTTP 200)
{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "status": 200,
        "body": {
          "success": true,
          "data": {
            "status": "completed",
            "output": [
              "https://cdn.example.com/result_0.png"
            ]
          }
        }
      },
      {
        "index": 1,
        "status": 200,
        "body": {
          "success": true,
          "data": {
            "status": "completed",
            "output": [
              "https://cdn.example.com/result_1.png"
            ]
          }
        }
      }
    ]
  }
}

More than 10 jobs

Split work across multiple HTTP calls. Each call may include up to 10 entries in requests. Space out calls if you need to limit load.