Atlas Cloud plugin

Query Atlas Cloud with SQL. Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API to access video generation, image generation, and LLM APIs — 300+ curated models across all modalities.

The plugin exposes five tables:

Installation

anyquery install atlascloud

You will be asked for:

• api_key (required): your Atlas Cloud API key. Create one in the Atlas Cloud console under Settings → API Keys.
• base_url (optional): an override of the API endpoint. Leave empty unless you know what you are doing.

⚠️ The llm, image and video_jobs tables make paid API calls. A join can fan out into one call per row — always test your query with a LIMIT first.

atlascloud_models

Lists every model available on Atlas Cloud, with the exact id to pass to the other tables.

-- List the available video models
SELECT id, name, provider FROM atlascloud_models WHERE modality = 'video';

The catalog is cached on disk for 6 hours. Force a refresh with SELECT clear_plugin_cache('atlascloud');.

atlascloud_llm

Runs a chat completion and returns one row per call.

Parameters can be passed either as WHERE clauses or as positional arguments to the table-valued function.

Table-valued function argument order: atlascloud_llm(model, prompt, system_prompt, temperature, max_tokens)

Output columns: response, finish_reason, prompt_tokens, completion_tokens.

-- 1. Simplest form: just model + prompt (trailing optional arguments omitted)
SELECT response FROM atlascloud_llm('qwen/qwen3-8b', 'Explain SQL in one sentence');

-- 2. Steer the model with the optional parameters (WHERE form)
SELECT response, finish_reason, prompt_tokens, completion_tokens
FROM atlascloud_llm
WHERE model = 'Qwen/Qwen3-30B-A3B-Instruct-2507'
  AND prompt = 'Name one SQL keyword'
  AND system_prompt = 'Answer with a single uppercase word.'
  AND temperature = 0.2
  AND max_tokens = 20;

-- 3. The same call as a table-valued function — all five arguments, in order:
--    (model, prompt, system_prompt, temperature, max_tokens)
SELECT response
FROM atlascloud_llm(
  'Qwen/Qwen3-30B-A3B-Instruct-2507',   -- model
  'Name one SQL keyword',               -- prompt
  'Answer with a single uppercase word.', -- system_prompt
  0.2,                                  -- temperature
  20                                    -- max_tokens
);

-- 4. Per-row LLM calls via a join: summarize your GitHub issues
SELECT title, response AS summary
FROM github_my_issues, atlascloud_llm
WHERE atlascloud_llm.model = 'deepseek-ai/DeepSeek-V3-0324'
  AND atlascloud_llm.prompt = 'Summarize in one sentence: ' || body
LIMIT 10;

Skipping optional arguments. You can drop trailing arguments (e.g. atlascloud_llm(model, prompt) or atlascloud_llm(model, prompt, system_prompt)). To set a later optional argument while skipping an earlier one, use the WHERE form — passing NULL or '' for a parameter is treated as a constraint that matches no rows and returns an empty result.

atlascloud_image

Generates an image and blocks until it is ready (polls every 2 seconds, gives up after 90 seconds — typical generations take 2–10 s).

Table-valued function argument order: atlascloud_image(model, prompt, image_url, extra_params)

Output columns:

-- text-to-image (table-valued function: model + prompt)
SELECT url, status, error
FROM atlascloud_image('black-forest-labs/flux-schnell', 'A serene Japanese garden, watercolor style');

-- Pass model-specific parameters with extra_params (merged into the request;
-- explicit columns win). Use the WHERE form to set extra_params without image_url.
SELECT url, status
FROM atlascloud_image
WHERE model = 'black-forest-labs/flux-schnell'
  AND prompt = 'A serene Japanese garden, watercolor style'
  AND extra_params = '{"seed": 42, "image_size": "1024x1024"}';

-- image-to-image / edit: provide a source image_url (3rd positional argument)
--   (model, prompt, image_url)
SELECT url, status
FROM atlascloud_image(
  'black-forest-labs/flux-kontext-dev',          -- model
  'Make it look like a snowy winter scene',      -- prompt
  'https://example.com/source.jpg'               -- image_url
);

A failed generation returns a row with status/error set instead of failing the query, so batch generation over a join continues past individual failures. Unsupported model parameters come back as a failed status with the API's error message.

atlascloud_video_jobs

Video generation takes 30 seconds to 3 minutes, so it is exposed as an async job table: INSERT submits a job and returns immediately; SELECT polls the pending jobs once and returns their current state. Jobs are persisted locally (per profile), so they survive across anyquery sessions.

Because submission happens through INSERT, parameters are given as named columns (order does not matter — name each one in the column list):

SELECT columns:

-- Submit a job
INSERT INTO atlascloud_video_jobs(model, prompt)
VALUES ('bytedance/seedance-2.0/text-to-video', 'Ocean waves at sunset');

-- Submit with model-specific parameters via extra_params
INSERT INTO atlascloud_video_jobs(model, prompt, extra_params)
VALUES ('bytedance/seedance-v1-pro-fast/text-to-video', 'Ocean waves at sunset', '{"duration": 5}');

-- image-to-video: provide a source image_url
INSERT INTO atlascloud_video_jobs(model, prompt, image_url)
VALUES ('bytedance/seedance-v1-pro-fast/image-to-video', 'Animate this photo with gentle camera motion', 'https://example.com/source.jpg');

-- … wait 30 s to 3 min, then poll
SELECT prediction_id, status, outputs FROM atlascloud_video_jobs;

-- Clean up finished jobs (removes them from the local store only)
DELETE FROM atlascloud_video_jobs WHERE status = 'completed';

Jobs already in a terminal state are returned from local storage without re-polling. The store keeps the 1000 most recent jobs per profile.

atlascloud_predictions

A read-only lookup of any Atlas Cloud prediction by its ID. Use it to recover an image generation that timed out — the generation was already paid for and usually finishes within a minute, but atlascloud_image stops blocking after 90 s — or to inspect any prediction without submitting a new (billable) generation. The lookup is a free GET and is never cached, so it always reflects the current state.

Table-valued function argument order: atlascloud_predictions(prediction_id)

Output columns:

-- Look up a prediction (e.g. one whose image generation timed out)
SELECT status, outputs, error
FROM atlascloud_predictions('e88145b3281945eba1749db1a151a190');

-- Equivalent WHERE form
SELECT status, outputs
FROM atlascloud_predictions
WHERE prediction_id = 'e88145b3281945eba1749db1a151a190';

Caveats

• Output URLs may expire. The image/video URLs are hosted by Atlas Cloud and may be temporary — download your outputs promptly.
• Duplicate-call protection. SQLite can re-scan a table during a query (joins, OR clauses). To avoid double-billing, llm and image results are memoized in memory for 5 minutes, keyed on the full input tuple. Within that window, the exact same call returns the same generation. A submit failure (which was never billed) is cached for only 30 s so a retry is not blocked. Restarting anyquery clears it; nothing is persisted.
• Generations are never cached on disk. Only the model catalog is cached. SELECT clear_plugin_cache('atlascloud') clears the catalog cache and the local video job list.
• Server mode timeouts. atlascloud_image can block up to 90 s inside a query. Some MySQL clients default to shorter read timeouts — raise your client's read timeout if needed. If an image times out, the generation usually still completes on Atlas Cloud: the error message includes a prediction_id you can fetch later with atlascloud_predictions.
• Rate limits and balance. HTTP 429 responses are retried with backoff (honoring Retry-After). "Insufficient balance" errors are surfaced as-is: top up in the Atlas Cloud console.
• Model-specific parameters (resolution, duration, seed…) vary per model and are passed through extra_params untouched. Check each model's page on Atlas Cloud for its schema.
• Don't pass NULL or '' to an optional parameter. Omit it instead. A NULL/empty-string equality constraint (e.g. system_prompt = '', or atlascloud_llm(model, prompt, NULL, 0.2)) matches no rows and returns an empty result. To set a later optional argument while skipping an earlier one, use the WHERE form.