getaiapi 1.0.0-alpha.3 → 1.0.1

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-TB6M4OFF.js}

@@ -30542,11 +30542,11 @@ var registry_default = [
         endpoint: "fal-ai/kling-video/create-voice",
         auth_env: "FAL_KEY",
         param_map: {
-          image: "images_data_url"
+          voice_url: "voice_url"
         },
         output_map: {
           type: "text",
-          extract_path: "video.url",
+          extract_path: "voice_id",
           content_type: "text/plain"
         }
       }
@@ -70674,6 +70674,356 @@ var registry_default = [
         }
       }
     ]
+  },
+  {
+    canonical_name: "gpt-5.4-pro",
+    aliases: [
+      "gpt-5.4-pro",
+      "openai-gpt-5.4-pro"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-gpt-5.4-pro",
+        endpoint: "openai/gpt-5.4-pro",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "gpt-5.4",
+    aliases: [
+      "gpt-5.4",
+      "openai-gpt-5.4"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-gpt-5.4",
+        endpoint: "openai/gpt-5.4",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "gpt-5.4-mini",
+    aliases: [
+      "gpt-5.4-mini",
+      "openai-gpt-5.4-mini"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-gpt-5.4-mini",
+        endpoint: "openai/gpt-5.4-mini",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "gemini-3.1-pro",
+    aliases: [
+      "gemini-3.1-pro",
+      "google-gemini-3.1-pro"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-gemini-3.1-pro",
+        endpoint: "google/gemini-3.1-pro-preview",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "grok-4.20",
+    aliases: [
+      "grok-4.20",
+      "xai-grok-4.20"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-grok-4.20",
+        endpoint: "x-ai/grok-4.20-beta",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "palmyra-x5",
+    aliases: [
+      "palmyra-x5",
+      "writer-palmyra-x5"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-palmyra-x5",
+        endpoint: "writer/palmyra-x5",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "gpt-5.4-nano",
+    aliases: [
+      "gpt-5.4-nano",
+      "openai-gpt-5.4-nano"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-gpt-5.4-nano",
+        endpoint: "openai/gpt-5.4-nano",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "mimo-v2-pro",
+    aliases: [
+      "mimo-v2-pro",
+      "xiaomi-mimo-v2-pro"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-mimo-v2-pro",
+        endpoint: "xiaomi/mimo-v2-pro",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "mimo-v2-omni",
+    aliases: [
+      "mimo-v2-omni",
+      "xiaomi-mimo-v2-omni"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-mimo-v2-omni",
+        endpoint: "xiaomi/mimo-v2-omni",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "mistral-small-4",
+    aliases: [
+      "mistral-small-4",
+      "mistralai-mistral-small-4"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-mistral-small-4",
+        endpoint: "mistralai/mistral-small-2603",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "minimax-m2.7",
+    aliases: [
+      "minimax-m2.7",
+      "minimax-m27"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-minimax-m2.7",
+        endpoint: "minimax/minimax-m2.7",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "nemotron-3-super",
+    aliases: [
+      "nemotron-3-super",
+      "nvidia-nemotron-3-super"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-nemotron-3-super",
+        endpoint: "nvidia/nemotron-3-super-120b-a12b",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "qwen-3.5-72b",
+    aliases: [
+      "qwen-3.5-72b",
+      "qwen-35-72b"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-qwen-3.5-72b",
+        endpoint: "qwen/qwen3.5-9b",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
+  },
+  {
+    canonical_name: "glm-5-turbo",
+    aliases: [
+      "glm-5-turbo",
+      "z-ai-glm-5-turbo"
+    ],
+    modality: {
+      inputs: ["text"],
+      outputs: ["text"]
+    },
+    providers: [
+      {
+        provider: "openrouter",
+        skill_id: "openrouter-glm-5-turbo",
+        endpoint: "z-ai/glm-5-turbo",
+        auth_env: "OPENROUTER_API_KEY",
+        param_map: { prompt: "prompt" },
+        output_map: {
+          type: "text",
+          extract_path: "choices[0].message.content",
+          content_type: "text/plain"
+        }
+      }
+    ]
   }
 ];
 
@@ -71935,8 +72285,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 +72314,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 +72484,11 @@ export {
   uploadAsset,
   presignAsset,
   deleteAsset,
+  submit,
+  poll,
+  submitAndPoll,
   generate,
   listModels,
   deriveCategory
 };
-//# sourceMappingURL=chunk-HNBZJY7Z.js.map
+//# sourceMappingURL=chunk-TB6M4OFF.js.map