# POST /api/v1/jobs/createTask

> Creates a generation task and returns its ID (taskId) right away. The price is charged now and refunded on failure.

## Request

```http
POST https://ai.aimixmedia.site/api/v1/jobs/createTask
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

## Parameters

| Field | Required | Description |
|---|---|---|
| `model` | yes | Model ID, e.g. `nano-banana-2` — [list](https://docs.aimixmedia.site/en/models) |
| `input` | yes | Model parameters: `prompt`, photos, etc. — see the model page |
| `callBackUrl` | no | Where to POST the result when the task finishes — [callback](https://docs.aimixmedia.site/en/callbacks) |

The optional `Idempotency-Key` header protects against duplicates on retries — [details](https://docs.aimixmedia.site/en/idempotency).

## Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_nano-banana-2_1790621023886ca4e4d"
  }
}
```

## Examples

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2","callBackUrl":"https://your-app.example/callback","input":{"prompt":"Poster \"Summer in Moscow\"","aspect_ratio":"3:4"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "nano-banana-2",
      "callBackUrl": "https://your-app.example/callback",
      "input": {
        "prompt": "Poster \"Summer in Moscow\"",
        "aspect_ratio": "3:4"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "nano-banana-2",
    "callBackUrl": "https://your-app.example/callback",
    "input": {
      "prompt": "Poster \"Summer in Moscow\"",
      "aspect_ratio": "3:4"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Errors

| code | error | When |
|---|---|---|
| 401 | `unauthorized` | Missing or invalid key |
| 402 | `insufficient_balance` | Not enough balance |
| 422 | `validation_error` | Invalid parameter (see `msg`) |
| 422 | `unsupported_model` | Unknown model |
| 429 | `rate_limited` | Too many requests |

All codes are in [Errors & limits](https://docs.aimixmedia.site/en/errors).