Batch AI Generation API: Submit, Poll, and Validate Jobs Safely

A batch generation client should be a queue with records, not a loop that fires every prompt at once. Each item needs a stable local ID, chosen model_id, validated input object, submission state, task_uuid, timestamps, terminal status, output, and error details. NamiFusion's Marketplace REST API submits one model run at POST /api/v1/marketplace/run/{model_id}; the response includes task_uuid and status. The client then reads GET /api/v1/marketplace/run/tasks/{task_uuid} until completed, failed, or cancelled. This asynchronous shape lets workers resume after interruption and prevents a long generation from holding one request open.

Discover the contract and prepare inputs

Create an API key on the API Keys page and store it outside source control. Before batching, call GET /api/v1/marketplace/models to find active models, then GET /api/v1/marketplace/models/detail?model_id={model_id} to read that model's current parameters. Build the request from this schema. Required fields must be present; optional fields should be included only when you intentionally set them or the model supplies an applicable default. Do not assume prompt, size, seed, or media keys are identical across models. Supply media in the format declared by the live parameter: commonly a reachable URL, or base64 only when that parameter explicitly supports automatic base64 upload.

Normalize the batch before spending credits. Reject duplicate local IDs, empty required prompts, unsupported URLs, and rows whose model differs from the schema used to validate them. Store a digest of the normalized request so an operator can detect accidental duplicates. Split mixed-model input into model-specific queues because validation, expected duration, cost, and concurrency policy may differ. Run one canary item per model and inspect the output contract before releasing the rest of the queue.

Submit and poll one task correctly

The request body wraps model fields inside input. Replace MODEL_ID and its example fields with values from the live model detail. A successful submission returns JSON containing task_uuid; save it before doing anything else. Poll the task route, not the model route, and stop only at completed, failed, or cancelled. On completed, read output without assuming it is always one URL; validate the current response shape. On failed or cancelled, persist the terminal response for diagnosis. Authentication may use Authorization: Bearer YOUR_API_KEY or X-API-Key. Never put a real key in code, logs, screenshots, or client-side JavaScript.

# 1) Submit — returns { "task_uuid": "...", "status": ... }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/MODEL_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"prompt":"A precise, model-compatible prompt"}}'

# 2) Poll until status is completed, failed, or cancelled
curl "https://www.namifusion.com/api/v1/marketplace/run/tasks/TASK_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Turn one task into a bounded batch

1. Read and validate all rows without submitting.
2. Send one canary and verify its terminal output.
3. Start a small worker pool rather than one worker per row.
4. For each pending row, persist “submitting,” send the request, then persist task_uuid and “submitted.” A network failure after sending is ambiguous; search your records and task list before deciding to resubmit.
5. Poll active UUIDs on a moderate interval with jitter.
6. Honor 429 responses and their retry guidance, and back off on temporary 5xx errors.
7. Stop polling terminal jobs.
8. Validate outputs and mark them approved or review-needed separately from API status.
9. Export a manifest mapping local ID to model, request digest, task_uuid, status, outputs, and review result.
10. Resume only unfinished rows after a process restart.

Validate outputs and diagnose failures

API success means the provider completed the task; it does not mean the media meets your brief. Verify that every expected output is present and reachable, then check file type, dimensions or duration, corruption, and task-specific content rules. For images, inspect anatomy, text, identities, and composition. For video, inspect opening fidelity, temporal warping, audio, and end frames. Retry only after classifying the cause. Invalid parameters require a schema or input fix. A content defect needs a prompt, reference, model, or settings revision. A temporary service failure may warrant a delayed retry. A failed job should not be resubmitted endlessly, and a completed-but-rejected output should be a new intentional revision with lineage to the original.

Rate limits, costs, and operational limits

Marketplace runs consume credits up front. Model prices, parameter-based cost, provider duration, timeouts, and output formats vary, so fetch current model detail and show the operator an estimated batch total before release. API-key calls use the account-wide API-key requests-per-minute bucket and may also have an explicit per-key rate_limit_per_minute. Do not encode a universal concurrency number in a guide or client. Make it configurable, lower it when 429 responses appear, and use server guidance. Set a maximum attempts count, maximum batch spend in your own scheduler, and a stop switch. Keep raw task records until reconciliation is complete. For very long model timeouts, retain task_uuid and continue later rather than treating a client deadline as proof of failure.