getaiapi 1.0.0-alpha.2 → 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-34X3VRM3.js → chunk-DZVZ5HSO.js}

@@ -32511,11 +32511,9 @@ var registry_default = [
           video: "video_url",
           image: "image_url",
           prompt: "prompt",
-          resolution: "resolution",
-          seed: "seed",
-          guidance: "guidance_scale",
-          steps: "num_inference_steps",
-          safety: "enable_safety_checker"
+          character_orientation: "character_orientation",
+          keep_audio: "keep_original_sound",
+          elements: "elements"
         },
         output_map: {
           type: "video",
@@ -32530,13 +32528,11 @@ var registry_default = [
         auth_env: "REPLICATE_API_TOKEN",
         param_map: {
           video: "video",
-          image: "character_image",
+          image: "image",
           prompt: "prompt",
-          resolution: "resolution",
-          seed: "seed",
-          guidance: "guidance_scale",
-          steps: "num_inference_steps",
-          safety: "enable_safety_checker"
+          character_orientation: "character_orientation",
+          mode: "mode",
+          keep_audio: "keep_original_sound"
         },
         output_map: {
           type: "video",
@@ -45366,15 +45362,15 @@ var registry_default = [
         auth_env: "FAL_KEY",
         param_map: {
           prompt: "prompt",
-          negative_prompt: "negative_prompt",
+          images: "image_urls",
           count: "num_images",
-          size: "image_size",
-          guidance: "guidance_scale",
-          steps: "num_inference_steps",
           seed: "seed",
+          resolution: "resolution",
+          aspect_ratio: "aspect_ratio",
           format: "output_format",
-          quality: "quality",
-          safety: "enable_safety_checker"
+          safety_tolerance: "safety_tolerance",
+          web_search: "enable_web_search",
+          thinking_level: "thinking_level"
         },
         output_map: {
           type: "image",
@@ -45389,18 +45385,12 @@ var registry_default = [
         auth_env: "REPLICATE_API_TOKEN",
         param_map: {
           prompt: "prompt",
-          negative_prompt: "negative_prompt",
-          count: "num_outputs",
-          size: [
-            "width",
-            "height"
-          ],
-          guidance: "guidance",
-          steps: "num_inference_steps",
-          seed: "seed",
+          images: "image_input",
+          resolution: "resolution",
+          aspect_ratio: "aspect_ratio",
           format: "output_format",
-          quality: "output_quality",
-          safety: "disable_safety_checker"
+          web_search: "google_search",
+          image_search: "image_search"
         },
         output_map: {
           type: "image",
@@ -45432,15 +45422,16 @@ var registry_default = [
         endpoint: "fal-ai/nano-banana-2/edit",
         auth_env: "FAL_KEY",
         param_map: {
-          image: "image_url",
-          images: "image_urls",
           prompt: "prompt",
-          strength: "strength",
-          mask: "mask_url",
+          images: "image_urls",
+          count: "num_images",
           seed: "seed",
+          resolution: "resolution",
+          aspect_ratio: "aspect_ratio",
           format: "output_format",
-          quality: "quality",
-          safety: "enable_safety_checker"
+          safety_tolerance: "safety_tolerance",
+          web_search: "enable_web_search",
+          thinking_level: "thinking_level"
         },
         output_map: {
           type: "image",
@@ -45454,15 +45445,11 @@ var registry_default = [
         endpoint: "google/nano-banana-2/edit",
         auth_env: "WAVESPEED_API_KEY",
         param_map: {
-          image: "image_url",
-          images: "image_urls",
           prompt: "prompt",
-          strength: "strength",
-          mask: "mask_url",
+          image: "image",
+          images: "image_urls",
           seed: "seed",
-          format: "output_format",
-          quality: "quality",
-          safety: "enable_safety_checker"
+          format: "output_format"
         },
         output_map: {
           type: "image",
@@ -48632,6 +48619,7 @@ var registry_default = [
     modality: {
       inputs: [
         "audio",
+        "text",
         "video"
       ],
       outputs: [
@@ -48646,13 +48634,9 @@ var registry_default = [
         auth_env: "FAL_KEY",
         param_map: {
           video: "video_url",
-          image: "image_url",
-          prompt: "prompt",
-          resolution: "resolution",
-          seed: "seed",
-          guidance: "guidance_scale",
-          steps: "num_inference_steps",
-          safety: "enable_safety_checker"
+          audio: "audio_url",
+          text: "text",
+          voice_id: "voice_id"
         },
         output_map: {
           type: "video",
@@ -48667,13 +48651,7 @@ var registry_default = [
         auth_env: "REPLICATE_API_TOKEN",
         param_map: {
           video: "video",
-          image: "character_image",
-          prompt: "prompt",
-          resolution: "resolution",
-          seed: "seed",
-          guidance: "guidance_scale",
-          steps: "num_inference_steps",
-          safety: "enable_safety_checker"
+          audio: "audio"
         },
         output_map: {
           type: "video",
@@ -48950,12 +48928,11 @@ var registry_default = [
         param_map: {
           video: "video_url",
           image: "image_url",
-          prompt: "prompt",
           resolution: "resolution",
           seed: "seed",
-          guidance: "guidance_scale",
-          steps: "num_inference_steps",
-          safety: "enable_safety_checker"
+          mode: "mode",
+          keep_audio: "original_sound_switch",
+          keyframe: "keyframe_id"
         },
         output_map: {
           type: "video",
@@ -64763,14 +64740,19 @@ var registry_default = [
         endpoint: "fal-ai/wan/v2.2-14b/animate/move",
         auth_env: "FAL_KEY",
         param_map: {
+          video: "video_url",
           image: "image_url",
-          prompt: "prompt",
-          negative_prompt: "negative_prompt",
+          resolution: "resolution",
           seed: "seed",
           guidance: "guidance_scale",
           steps: "num_inference_steps",
-          format: "output_format",
-          safety: "enable_safety_checker"
+          safety: "enable_safety_checker",
+          shift: "shift",
+          video_write_mode: "video_write_mode",
+          video_quality: "video_quality",
+          turbo: "use_turbo",
+          output_safety: "enable_output_safety_checker",
+          return_frames_zip: "return_frames_zip"
         },
         output_map: {
           type: "video",
@@ -64804,12 +64786,17 @@ var registry_default = [
         param_map: {
           video: "video_url",
           image: "image_url",
-          prompt: "prompt",
           resolution: "resolution",
           seed: "seed",
           guidance: "guidance_scale",
           steps: "num_inference_steps",
-          safety: "enable_safety_checker"
+          safety: "enable_safety_checker",
+          shift: "shift",
+          video_write_mode: "video_write_mode",
+          video_quality: "video_quality",
+          turbo: "use_turbo",
+          output_safety: "enable_output_safety_checker",
+          return_frames_zip: "return_frames_zip"
         },
         output_map: {
           type: "video",
@@ -64825,12 +64812,10 @@ var registry_default = [
         param_map: {
           video: "video",
           image: "character_image",
-          prompt: "prompt",
           resolution: "resolution",
           seed: "seed",
-          guidance: "guidance_scale",
-          steps: "num_inference_steps",
-          safety: "enable_safety_checker"
+          keep_audio: "merge_audio",
+          turbo: "go_fast"
         },
         output_map: {
           type: "video",
@@ -71950,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());
@@ -71980,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),
@@ -72076,8 +72134,11 @@ export {
   uploadAsset,
   presignAsset,
   deleteAsset,
+  submit,
+  poll,
+  submitAndPoll,
   generate,
   listModels,
   deriveCategory
 };
-//# sourceMappingURL=chunk-34X3VRM3.js.map
+//# sourceMappingURL=chunk-DZVZ5HSO.js.map