# Scenepond API — API documentation

Source page: https://open.scenepond.ai/en/docs

Connect your application to an enabled model using the gateway URL and a Scenepond API key.

## 1. Prepare your API key

Create a key in the customer console. Keep the secret in a server-side environment variable named SCENEPOND_API_KEY. The website login session is not an API key.

```bash
export SCENEPOND_API_KEY="YOUR_SCENEPOND_API_KEY"
```

## 2. Set your base URL

`https://scenepond-api-production.up.railway.app/v1`

Send Authorization: Bearer with your API key. Use HTTPS and keep keys out of browser code and URLs.

## 3. Send a request

This example uses deepseek-flash. Confirm that your API key has access and your account has sufficient balance before sending a request.

### cURL

```bash
curl "https://scenepond-api-production.up.railway.app/v1/chat/completions" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "deepseek-flash",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "stream": false
}
JSON
```

### Python

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SCENEPOND_API_KEY"],
    base_url="https://scenepond-api-production.up.railway.app/v1"
)
response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

### JavaScript

```javascript
const response = await fetch("https://scenepond-api-production.up.railway.app/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "deepseek-flash",
    messages: [{ role: "user", content: "Hello!" }],
    stream: false
  })
});
if (!response.ok) throw new Error(`API error: ${response.status}`);
const result = await response.json();
console.log(result.choices[0].message.content);
```

This example uses the chat completions protocol. Image, video, and task APIs can use different request schemas; check each model’s endpoint and configured provider before integrating.

## Asynchronous tasks

Image and video task APIs return an ID before generation finishes. Submit once, preserve the ID, poll status, and retrieve media after successful completion.

- `POST /v1/tasks/fal`: Submit a model-specific generation request; returns task_id.
- `GET /v1/tasks/{task_id}`: Read status, progress, and fail_reason. This response does not contain generated media.
- `GET /v1/tasks/{task_id}/artifacts`: After SUCCESS, read the artifacts and their content_url values.

Use the model page for exact required fields, optional generation settings, and Video or Responses compatibility. Video Responses require background:true; this does not apply to text-model Responses.

Use the same account API key to retrieve task results. Wait for SUCCESS or completed before downloading; on FAILURE or failed, inspect the returned error. Do not blindly repeat a paid POST after a timeout.

## 4. Monitor balance and usage

Requests are settled by the existing backend. Compare the configured model price before calling and review actual charges in your usage records.

[Models & pricing](https://open.scenepond.ai/en/models)

[Usage records](https://open.scenepond.ai/en/account)

## Handle API errors

- `400`: Check the model ID, required fields, types, and allowed parameter values.
- `401`: Check the API key and whether it is enabled.
- `403`: Check key restrictions and model permissions.
- `429`: Respect the returned retry delay and lower your request rate.
- `5xx`: Inspect the error response. Avoid blindly retrying paid generation requests.

## Tool integrations

Configure Hermes, OpenClaw, IDEs, Dify, or n8n in the dedicated tool integration guides.

[Explore integration guides](https://open.scenepond.ai/en/integrations)

## Model API documentation

Choose a model to view its API protocol and request examples.

- [Wan 3.0 Prime](https://open.scenepond.ai/en/docs/models/alibaba%2Fwan-3.0-prime%2Fimage-to-video.md) — `alibaba/wan-3.0-prime/image-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/alibaba%2Fwan-3.0-prime%2Fimage-to-video#api)
- [Wan 3.0 Prime](https://open.scenepond.ai/en/docs/models/alibaba%2Fwan-3.0-prime%2Ftext-to-video.md) — `alibaba/wan-3.0-prime/text-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/alibaba%2Fwan-3.0-prime%2Ftext-to-video#api)
- [Wan 3.0](https://open.scenepond.ai/en/docs/models/alibaba%2Fwan-3.0%2Fimage-to-video.md) — `alibaba/wan-3.0/image-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/alibaba%2Fwan-3.0%2Fimage-to-video#api)
- [Wan 3.0](https://open.scenepond.ai/en/docs/models/alibaba%2Fwan-3.0%2Ftext-to-video.md) — `alibaba/wan-3.0/text-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/alibaba%2Fwan-3.0%2Ftext-to-video#api)
- [FLUX 3 Draft](https://open.scenepond.ai/en/docs/models/blackforestlabs%2Fflux-3%2Fimage-to-video%2Fdraft.md) — `blackforestlabs/flux-3/image-to-video/draft` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/blackforestlabs%2Fflux-3%2Fimage-to-video%2Fdraft#api)
- [FLUX 3 Draft](https://open.scenepond.ai/en/docs/models/blackforestlabs%2Fflux-3%2Ftext-to-video%2Fdraft.md) — `blackforestlabs/flux-3/text-to-video/draft` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/blackforestlabs%2Fflux-3%2Ftext-to-video%2Fdraft#api)
- [DeepSeek Flash](https://open.scenepond.ai/en/docs/models/deepseek-flash.md) — `deepseek-flash` · openai, openai-response, anthropic · [Source page](https://open.scenepond.ai/en/models/deepseek-flash#api)
- [DeepSeek V4 Pro](https://open.scenepond.ai/en/docs/models/deepseek-v4-pro.md) — `deepseek-v4-pro` · openai, openai-response, anthropic · [Source page](https://open.scenepond.ai/en/models/deepseek-v4-pro#api)
- [Gemini Omni 1.1 Flash](https://open.scenepond.ai/en/docs/models/google%2Fgemini-omni-flash%2Fv1.1%2Fimage-to-video.md) — `google/gemini-omni-flash/v1.1/image-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/google%2Fgemini-omni-flash%2Fv1.1%2Fimage-to-video#api)
- [Gemini Omni 1.1 Flash](https://open.scenepond.ai/en/docs/models/google%2Fgemini-omni-flash%2Fv1.1%2Ftext-to-video.md) — `google/gemini-omni-flash/v1.1/text-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/google%2Fgemini-omni-flash%2Fv1.1%2Ftext-to-video#api)
- [LTX-2.5 Fast](https://open.scenepond.ai/en/docs/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Ffast.md) — `lightricks/ltx-2.5/image-to-video/fast` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Ffast#api)
- [LTX-2.5 Pro](https://open.scenepond.ai/en/docs/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Fpro.md) — `lightricks/ltx-2.5/image-to-video/pro` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Fpro#api)
- [LTX-2.5 Fast](https://open.scenepond.ai/en/docs/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Ffast.md) — `lightricks/ltx-2.5/text-to-video/fast` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Ffast#api)
- [LTX-2.5 Pro](https://open.scenepond.ai/en/docs/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Fpro.md) — `lightricks/ltx-2.5/text-to-video/pro` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Fpro#api)
- [Muse Image](https://open.scenepond.ai/en/docs/models/meta%2Fmuse-image%2Ftext-to-image.md) — `meta/muse-image/text-to-image` · fal-task · [Source page](https://open.scenepond.ai/en/models/meta%2Fmuse-image%2Ftext-to-image#api)
- [MiniMax H3 Max Turbo](https://open.scenepond.ai/en/docs/models/minimax%2Fh3-max-turbo%2Fimage-to-video.md) — `minimax/h3-max-turbo/image-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/minimax%2Fh3-max-turbo%2Fimage-to-video#api)
- [MiniMax H3 Max Turbo](https://open.scenepond.ai/en/docs/models/minimax%2Fh3-max-turbo%2Ftext-to-video.md) — `minimax/h3-max-turbo/text-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/minimax%2Fh3-max-turbo%2Ftext-to-video#api)
- [MiniMax H3 Max](https://open.scenepond.ai/en/docs/models/minimax%2Fh3-max%2Fimage-to-video.md) — `minimax/h3-max/image-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/minimax%2Fh3-max%2Fimage-to-video#api)
- [MiniMax H3 Max](https://open.scenepond.ai/en/docs/models/minimax%2Fh3-max%2Ftext-to-video.md) — `minimax/h3-max/text-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/minimax%2Fh3-max%2Ftext-to-video#api)
- [MiniMax H3](https://open.scenepond.ai/en/docs/models/minimax%2Fh3%2Fimage-to-video.md) — `minimax/h3/image-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/minimax%2Fh3%2Fimage-to-video#api)
- [MiniMax H3](https://open.scenepond.ai/en/docs/models/minimax%2Fh3%2Ftext-to-video.md) — `minimax/h3/text-to-video` · fal-task, openai-video, openai-response · [Source page](https://open.scenepond.ai/en/models/minimax%2Fh3%2Ftext-to-video#api)
- [Recraft V4.1 Flash](https://open.scenepond.ai/en/docs/models/recraft%2Fv4.1%2Fflash%2Ftext-to-image.md) — `recraft/v4.1/flash/text-to-image` · fal-task · [Source page](https://open.scenepond.ai/en/models/recraft%2Fv4.1%2Fflash%2Ftext-to-image#api)
- [Grok Imagine Image 2.0](https://open.scenepond.ai/en/docs/models/xai%2Fgrok-imagine-image%2Fv2.0%2Fedit.md) — `xai/grok-imagine-image/v2.0/edit` · fal-task · [Source page](https://open.scenepond.ai/en/models/xai%2Fgrok-imagine-image%2Fv2.0%2Fedit#api)
- [Grok Imagine Image 2.0](https://open.scenepond.ai/en/docs/models/xai%2Fgrok-imagine-image%2Fv2.0%2Ftext-to-image.md) — `xai/grok-imagine-image/v2.0/text-to-image` · fal-task · [Source page](https://open.scenepond.ai/en/models/xai%2Fgrok-imagine-image%2Fv2.0%2Ftext-to-image#api)