# Flux 3 Action API

> Μοντέλο πολιτικής ρομπότ που προβλέπει τμήματα ενεργειών του βραχίονα SO-101 από καρέ κάμερας, κατάσταση αρθρώσεων και οδηγία

Αντί για πολυμέσα, επιστρέφει JSON με τις προβλεπόμενες `actions`, τον ρυθμό ελέγχου τους, τις ετικέτες στηλών και πόσα αρχικά βήματα πρέπει να εκτελεστούν (`execute_steps`) πριν ζητηθεί νέο τμήμα. Απαιτούμενες είσοδοι είναι ένα κείμενο `prompt` (έως 2000 χαρακτήρες), τα `scene_image_url`, `wrist_image_url` και μια `state` 6 τιμών. Προαιρετικές είσοδοι ιστορικού (`state_history`, `command_history`, εικόνες ιστορικού) παρέχουν χρονικό πλαίσιο. Το `num_inference_steps` κυμαίνεται από 1 έως 8 και το `guidance_scale` από 1 έως 10.

- Model id: `flux-3-action/so101`
- Made by: Black Forest Labs
- Category: Video to Video
- Output: json
- Estimated price per run: $0.003 / run (cheapest run $0.003 (3 API credits))
- Run: `POST https://api.doitong.com/v1/run/flux-3-action/so101`
- Quote: `POST https://api.doitong.com/v1/quote/flux-3-action/so101`
- Docs page: https://doitong.com/el/developers/models/flux-3-action/so101

## Pricing

Price: **$0.003 / run**. Estimated from the typical cost of one run. The quote is exactly what the run charges.

The full example input below costs $0.003 = 3 API credits (1 request × 3 API credits).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.com/v1/quote/flux-3-action/so101` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `prompt` |  | string | yes |  | 1 – 2000 characters | Οδηγίες εργασιών ρομπότ διατυπωμένες σε φυσική γλώσσα. |
| `scene_image_url` |  | string (image URL) | yes |  |  | Εικόνα αριστερού πλακιδίου που εμφανίζει το τρέχον καρέ της σταθερής κάμερας σκηνής μετά την αλλαγή μεγέθους σε 256x256. |
| `wrist_image_url` |  | string (image URL) | yes |  |  | Τρέχον καρέ της κάμερας καρπού, τοποθετημένο στο δεξί πλακίδιο και με αλλαγή μεγέθους σε 256x256. |
| `state` |  | array of number | yes |  | 6 – 6 items | Μετρημένες τιμές κατάστασης με τη σειρά: περιστροφή και ανύψωση ώμου, κάμψη αγκώνα, κάμψη και περιστροφή καρπού, όλες σε μοίρες, και έπειτα θέση αρπάγης ως ποσοστό. |
| `state_history` |  | array of array of number \| null | no |  | 7 – 7 items | Ιστορικό μετρημένης κατάστασης, παραλείπεται για νέο επεισόδιο και διαφορετικά απαιτεί `command_history`. Παρέχετε τις μετρήσεις με χρονολογική σειρά για τα 7 control ticks αμέσως πριν από το `state`, στα 30 Hz. |
| `command_history` |  | array of array of number \| null | no |  | 8 – 8 items | Ιστορικό απόλυτων εντολών που απαιτεί `state_history`, με την πιο πρόσφατα απεσταλμένη εντολή στην τελευταία γραμμή. Οι γραμμές εκτείνονται χρονολογικά σε 8 ticks παρατήρησης και καθορίζουν την εντολή που ισχύει σε κάθε tick. |
| `history_scene_image_url` |  | string (image URL) \| null | no |  |  | Είσοδος καρέ σκηνής από το ιστορικό που απαιτεί `state_history`· αν παραλειφθεί, χρησιμοποιείται το τρέχον καρέ. Το παρεχόμενο καρέ αντιστοιχεί στην παλαιότερη παρατήρηση του ιστορικού, 7 ticks πριν. |
| `history_wrist_image_url` |  | string (image URL) \| null | no |  |  | Καρέ κάμερας καρπού στο παλαιότερο tick του ιστορικού· απαιτείται `state_history`. |
| `num_inference_steps` |  | integer | no | `4` | 1 – 8 | Αριθμός βημάτων αποθορυβοποίησης Euler· η επικύρωση checkpoint χρησιμοποίησε 4 βήματα. |
| `guidance_scale` |  | number | no | `3` | 1 – 10 | Ισχύς classifier-free guidance για βίντεο και ενέργεια· ορίστε την σε 1.0 για απενεργοποίηση του CFG. |
| `seed` |  | integer \| null | no |  |  | Seed δειγματοληψίας με ρυθμίσεις αξιολόγησης αναφοράς του DROID: 0 και του SO-101: 42. Αν παραλειφθεί, επιλέγεται τυχαία seed. |

File parameters (`scene_image_url`, `wrist_image_url`, `history_scene_image_url`, `history_wrist_image_url`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
  "scene_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
  "wrist_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
  "state": [
    -18.94,
    134.52,
    120.15,
    28.3,
    -32.17,
    27.02
  ]
}
```

A fuller example:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
  "scene_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
  "wrist_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
  "state": [
    -18.94,
    134.52,
    120.15,
    28.3,
    -32.17,
    27.02
  ]
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.com/v1/run/flux-3-action/so101?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "scene_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "wrist_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "state": [
      -18.94,
      134.52,
      120.15,
      28.3,
      -32.17,
      27.02
    ]
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.com/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.com/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/flux-3-action/so101?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "scene_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "wrist_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "state": [
      -18.94,
      134.52,
      120.15,
      28.3,
      -32.17,
      27.02
    ]
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.com/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "scene_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "wrist_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "state": [
        -18.94,
        134.52,
        120.15,
        28.3,
        -32.17,
        27.02,
    ],
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/flux-3-action/so101", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.com/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "flux-3-action/so101",
      "input": {
        "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
        "scene_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
        "wrist_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
        "state": [
          -18.94,
          134.52,
          120.15,
          28.3,
          -32.17,
          27.02
        ]
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux-3-action/so101",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 3,
    "usd": "0.003",
    "charged": 3,
    "refunded": 0
  },
  "input": {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "scene_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "wrist_image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
    "state": [
      -18.94,
      134.52,
      120.15,
      28.3,
      -32.17,
      27.02
    ]
  },
  "output": {
    "actions": [
      [
        1.0
      ]
    ],
    "action_labels": [
      "string"
    ],
    "action_hz": 1.0,
    "execute_steps": 1,
    "seed": 42,
    "timings": {}
  },
  "outputs": [
    {
      "type": "file",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `actions` | array of array of number | Πίνακας προβλεπόμενων ενεργειών με χρονολογικές γραμμές που αναπαριστούν βήματα ελέγχου· οι τιμές δεν περιορίζονται, επομένως τα όρια αρθρώσεων, ταχυτήτων και χώρου εργασίας πρέπει να επιβάλλονται στο ρομπότ. Στα 30 Hz, το SO-101 παρέχει 42x6 απόλυτες εντολές σε deg και gripper %· στα 15 Hz, το DROID παρέχει 32x8 απόλυτους στόχους αρθρώσεων σε rad συν το κλάσμα κλεισίματος της αρπάγης. |
| `action_labels` | array of string | Ονόματα που αντιστοιχούν στις στήλες ενεργειών. |
| `action_hz` | number | Συχνότητα ελέγχου για τις γραμμές ενεργειών. |
| `execute_steps` | integer | Αριθμός αρχικών ενεργειών προς εκτέλεση πριν από την αίτηση νέου τμήματος. |
| `seed` | integer | Τυχαίο seed που χρησιμοποιείται κατά τη δειγματοληψία. |
| `timings` | object | Μετρήσεις χρονισμού από τον διακομιστή, εκφρασμένες σε δευτερόλεπτα. |

## Related models

- [Flux 3 Draft Enhance](https://doitong.com/developers/models/blackforestlabs/flux-3/draft-enhance.md) (`blackforestlabs/flux-3/draft-enhance`): $3.48 / run
- [Flux 3 Extend Video](https://doitong.com/developers/models/blackforestlabs/flux-3/extend-video.md) (`blackforestlabs/flux-3/extend-video`): from $0.41 / second
- [Flux 3 Extend Video Draft](https://doitong.com/developers/models/blackforestlabs/flux-3/extend-video/draft.md) (`blackforestlabs/flux-3/extend-video/draft`): $0.12 / second
- [Flux 3 FAST Edit Video](https://doitong.com/developers/models/blackforestlabs/flux-3/edit-video.md) (`blackforestlabs/flux-3/edit-video`): $0.03 / second of input video
- [AMT Interpolation](https://doitong.com/developers/models/amt-interpolation.md) (`amt-interpolation`): $0.000575 / second of processing time
- [AnimateDiff Turbo · Video to Video](https://doitong.com/developers/models/fast-animatediff/turbo/video-to-video.md) (`fast-animatediff/turbo/video-to-video`): $0.00125 / second of processing time
- [AnimateDiff · Video to Video](https://doitong.com/developers/models/fast-animatediff/video-to-video.md) (`fast-animatediff/video-to-video`): $0.00125 / second of processing time
- [Auto-Captioner](https://doitong.com/developers/models/auto-caption.md) (`auto-caption`): $0.10 / video

## Links

- HTML page: https://doitong.com/developers/models/flux-3-action/so101
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=flux-3-action/so101
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/flux-3-action/so101