getaiapi 1.0.0-alpha.3 → 1.0.0-alpha.4

package/README.md

@@ -115,6 +115,48 @@ const cutout = await generate({
 })
 ```
 
+## Async Job Control
+
+For long-running jobs (video generation, training), you can submit a job and poll for status separately instead of blocking until completion.
+
+```typescript
+import { submit, poll } from 'getaiapi'
+
+// Submit — returns immediately with the provider's task ID
+const job = await submit({
+  model: 'veo3.1',
+  prompt: 'a timelapse of a flower blooming',
+})
+
+console.log(job.id)     // provider task ID
+console.log(job.status) // 'pending' | 'processing' | 'completed'
+
+// Poll — check status manually (call in a loop, on a timer, etc.)
+let result = await poll(job)
+
+while (result.status === 'pending' || result.status === 'processing') {
+  await new Promise(r => setTimeout(r, 2000))
+  result = await poll(job)
+}
+
+if (result.status === 'completed') {
+  console.log(result.outputs[0].url)
+}
+```
+
+Synchronous providers (like OpenRouter) return `status: 'completed'` from `submit()` immediately -- check status before polling.
+
+`submitAndPoll()` is an alias for `generate()` that makes the blocking behavior explicit:
+
+```typescript
+import { submitAndPoll } from 'getaiapi'
+
+const result = await submitAndPoll({
+  model: 'flux-schnell',
+  prompt: 'a cat in space',
+})
+```
+
 ## Configuration
 
 ### Option 1: Environment Variables
@@ -302,6 +344,40 @@ interface OutputItem {
 }
 ```
 
+### `submit(request: GenerateRequest): Promise<SubmitResponse>`
+
+Submits a job to the provider and returns immediately without waiting for completion. Returns the provider's task ID and enough context to poll later.
+
+```typescript
+interface SubmitResponse {
+  id: string              // provider's task/request ID
+  model: string           // canonical model name
+  provider: ProviderName  // which provider handled it
+  endpoint: string        // needed for polling
+  status: 'pending' | 'processing' | 'completed'
+}
+```
+
+### `poll(job: SubmitResponse): Promise<PollResponse>`
+
+Checks the status of a submitted job once. Returns current status, and includes mapped outputs and metadata when completed.
+
+```typescript
+interface PollResponse {
+  id: string
+  model: string
+  provider: ProviderName
+  status: 'completed' | 'failed' | 'processing' | 'pending'
+  outputs?: OutputItem[]                   // populated when completed
+  metadata?: GenerateResponse['metadata']  // populated when completed
+  error?: string                           // populated when failed
+}
+```
+
+### `submitAndPoll(request: GenerateRequest): Promise<GenerateResponse>`
+
+Alias for `generate()`. Submits a job and polls until completion. Use this when you want the blocking behavior but want to be explicit about it.
+
 ### `listModels(filters?: ListModelsFilters): ModelEntry[]`
 
 Returns all models in the registry. Accepts optional filters:

package/dist/{chunk-HNBZJY7Z.js → chunk-DZVZ5HSO.js}

@@ -71935,8 +71935,7 @@ var adapters = {
   "openrouter": openRouterAdapter
 };
 var DEFAULT_TIMEOUT_MS = 12e4;
-async function generate(request) {
-  const startTime = Date.now();
+async function _prepare(request) {
   if (!request.model) throw new ValidationError("model", "model is required");
   const auth = new AuthManager();
   const model = resolveModel(request.model, auth.availableProviders());
@@ -71965,6 +71964,80 @@ async function generate(request) {
   });
   const adapter = adapters[binding.provider];
   const apiKey = auth.getKey(binding.provider);
+  return { binding, adapter, apiKey, finalParams, model };
+}
+async function submit(request) {
+  const { binding, adapter, apiKey, finalParams, model } = await _prepare(request);
+  const timeoutMs = request.options?.timeout ?? DEFAULT_TIMEOUT_MS;
+  const submitted = await withRetry(
+    () => adapter.submit(binding.endpoint, finalParams, apiKey),
+    { timeoutMs, provider: binding.provider, model: model.canonical_name }
+  );
+  return {
+    id: submitted.id,
+    model: model.canonical_name,
+    provider: binding.provider,
+    endpoint: binding.endpoint,
+    status: submitted.status === "completed" ? "completed" : submitted.status
+  };
+}
+async function poll(job) {
+  const adapter = adapters[job.provider];
+  if (!adapter) {
+    throw new ValidationError("provider", `Unknown provider "${job.provider}"`);
+  }
+  const auth = new AuthManager();
+  const apiKey = auth.getKey(job.provider);
+  const result = await adapter.poll(job.id, apiKey, job.endpoint);
+  if (result.status === "completed") {
+    const model = resolveModel(job.model, auth.availableProviders());
+    const binding = model.providers.find((p) => p.provider === job.provider);
+    if (!binding) {
+      throw new ProviderError(job.provider, job.model, 0, "Could not resolve provider binding for output mapping");
+    }
+    const outputs = mapOutput(result.output, binding.output_map);
+    const rawOutput = typeof result.output === "object" && result.output !== null ? result.output : void 0;
+    const metadata = {
+      seed: rawOutput?.seed,
+      safety_flagged: rawOutput ? Array.isArray(rawOutput.has_nsfw_concepts) ? rawOutput.has_nsfw_concepts.some((v) => v) : void 0 : void 0
+    };
+    if (rawOutput?.usage) {
+      const usage = rawOutput.usage;
+      metadata.tokens = usage.total_tokens;
+      metadata.prompt_tokens = usage.prompt_tokens;
+      metadata.completion_tokens = usage.completion_tokens;
+    }
+    return {
+      id: job.id,
+      model: job.model,
+      provider: job.provider,
+      status: "completed",
+      outputs,
+      metadata
+    };
+  }
+  if (result.status === "failed") {
+    return {
+      id: job.id,
+      model: job.model,
+      provider: job.provider,
+      status: "failed",
+      error: result.error || "Generation failed"
+    };
+  }
+  return {
+    id: job.id,
+    model: job.model,
+    provider: job.provider,
+    status: result.status
+  };
+}
+async function submitAndPoll(request) {
+  return generate(request);
+}
+async function generate(request) {
+  const startTime = Date.now();
+  const { binding, adapter, apiKey, finalParams, model } = await _prepare(request);
   const timeoutMs = request.options?.timeout ?? DEFAULT_TIMEOUT_MS;
   const submitted = await withRetry(
     () => adapter.submit(binding.endpoint, finalParams, apiKey),
@@ -72061,8 +72134,11 @@ export {
   uploadAsset,
   presignAsset,
   deleteAsset,
+  submit,
+  poll,
+  submitAndPoll,
   generate,
   listModels,
   deriveCategory
 };
-//# sourceMappingURL=chunk-HNBZJY7Z.js.map
+//# sourceMappingURL=chunk-DZVZ5HSO.js.map