# ID-V2V API

> Hubadilisha mtindo wa video kutoka kwa fremu ya kwanza iliyobadilishwa huku ikihifadhi utambulisho na mwendo wa mhusika

Huzalisha upya video ya chanzo (`video_url`) kwa mwonekano wa fremu ya kwanza iliyobadilishwa (`image_url`), ikiongozwa na `prompt`. Hadi `keyframes` 5 zinaweza kushikilia utambulisho katika klipu ndefu. Matokeo ni 480p au 720p yenye `num_frames` kutoka 17 hadi 241, na `segmentation_prompt` (person kwa chaguomsingi) huchagua mhusika ambaye pikseli zake huongoza matokeo.

- Model id: `id-v2v`
- Made by: Open model
- Category: Video to Video
- Output: video
- Price per second of your output video: $0.20 / second of output video (cheapest run $0.20 (200 API credits))
- Run: `POST https://api.doitong.com/v1/run/id-v2v`
- Quote: `POST https://api.doitong.com/v1/quote/id-v2v`
- Docs page: https://doitong.com/sw/developers/models/id-v2v

## Pricing

Price: **$0.20 / second of output video**. Price per second of your output video: the input files are measured before the run (length, resolution, frame rate). The quote measures the same files and is exactly what the run charges.

The full example input below costs $1.013 = 1013 API credits (5.0625 s output video × $0.20).

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/id-v2v` 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

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `prompt` |  | string | yes |  |  | Kidokezo kinachobainisha video iliyorekebishwa inayotakiwa. |
| `video_url` | `video` | string (video URL) | yes |  |  | Marejeleo ya mwendo na fremu kwa uzalishaji, yanayotolewa kama URL ya video chanzo. |
| `image_url` | `image` | string (image URL) | yes |  |  | Marejeleo ya utambulisho na mtindo kwa uzalishaji upya wa video, yanayotolewa kama URL inayoelekeza kwenye fremu ya kwanza iliyorekebishwa. |
| `keyframes` |  | array of object {image_url, frame_index} | no |  | ≤ 5 items | Viashiria vya hiari vya utambulisho kwa video ndefu: toa fremu muhimu zilizorekebishwa pamoja na faharasa za fremu za tokeo zinapopaswa kuonekana. |
| `keyframes[].image_url` |  | string (image URL) | yes |  |  | URL ya picha iliyorekebishwa kwa kiashiria cha utambulisho katika video ndefu; uwiano wa picha lazima utofautiane na wa tokeo kwa isiyozidi 0.1. Picha huonekana bila mabadiliko kwenye `frame_index`. |
| `keyframes[].frame_index` |  | integer | yes |  | ≥ 1 | Weka fremu muhimu katika nafasi ya tokeo ya angalau 1 na iliyo chini ya jumla ya fremu za tokeo, ukitumia faharasa ya kuanzia 0. Nafasi 0 imetengwa kwa fremu ya mwanzo iliyorekebishwa kutoka `image_url`. |
| `resolution` |  | enum (string) | no | `720p` | `480p`, `720p` | Chagua 720p kwa tokeo la 1280×720 au 720×1280, au 480p kwa tokeo la 832×480 au 480×832. Mwelekeo wa video chanzo huamua vipimo vitakavyotumika. |
| `num_frames` |  | integer | no | `81` | 17 – 241 | Punguza idadi ya fremu za kuzalisha; ikiwa chanzo kina fremu chache, idadi yake ya fremu huwa kikomo cha juu. |
| `segmentation_prompt` |  | string | no | `person` | ≤ 100 characters | Kidokezo cha kuchagua mada kwa SAM-3, kinachobainisha eneo ambalo pikseli zake zitaongoza uzalishaji. Nje ya mada hiyo iliyogawanywa, uzalishaji hauna vikwazo. |
| `num_inference_steps` |  | integer | no | `30` | 2 – 40 | Udhibiti wa ubora na kasi ya klipu unaoonyeshwa kama idadi ya hatua za sampuli za diffusion kwa kila klipu: kutumia hatua nyingi huboresha ubora lakini huchukua muda zaidi. |
| `guidance_scale` |  | number | no | `5` | 1 – 10 | Nguvu ya mwongozo usio na klasifaya, inayosawazisha ufuasi wa kidokezo na ubunifu. |
| `vace_scale` |  | number | no | `1` | 0 – 2 | Ufuasi wa muundo wa video chanzo, unaorekebishwa kupitia kipimo cha kuweka masharti cha VACE. |
| `seed` |  | integer \| null | no |  |  | Mbegu ya nasibu inayoshirikiwa na klipu zote wakati wa kuzalisha klipu nyingi, ikiruhusu uzalishaji unaoweza kurudiwa. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Huwasha ukaguzi wa usalama kwenye maingizo na matokeo. |

File parameters (`video`, `image`) 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",
  "video": "https://content.doitong.com/video/showcase/v3/gen_fox_cartoon.mp4",
  "image": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
}
```

A fuller example:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
  "video_url": "https://content.doitong.com/video/showcase/v3/gen_fox_cartoon.mp4",
  "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
}
```

## 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/id-v2v?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",
    "video_url": "https://content.doitong.com/video/showcase/v3/gen_fox_cartoon.mp4",
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  }'

# 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/id-v2v?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",
    "video_url": "https://content.doitong.com/video/showcase/v3/gen_fox_cartoon.mp4",
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  }),
});
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",
    "video_url": "https://content.doitong.com/video/showcase/v3/gen_fox_cartoon.mp4",
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/id-v2v", 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": "id-v2v",
      "input": {
        "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
        "video_url": "https://content.doitong.com/video/showcase/v3/gen_fox_cartoon.mp4",
        "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
      },
      "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": "id-v2v",
  "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": 1013,
    "usd": "1.013",
    "charged": 1013,
    "refunded": 0
  },
  "input": {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "video_url": "https://content.doitong.com/video/showcase/v3/gen_fox_cartoon.mp4",
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  },
  "output": {
    "video": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp4",
      "content_type": "video/mp4",
      "file_name": "0-output.mp4",
      "file_size": 1843200
    },
    "seed": 42
  },
  "outputs": [
    {
      "type": "video",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp4",
      "content_type": "video/mp4",
      "file_size": 1843200,
      "width": 1280,
      "height": 720,
      "duration": 5,
      "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 |
|---|---|---|
| `video` | object {url, content_type, file_name, file_size} | Faili ya video iliyozalishwa. |
| `seed` | integer | Thamani ya seed inayotumika wakati wa uzalishaji. |

## Related models

- [ID-V2V Relight](https://doitong.com/developers/models/id-v2v/relight.md) (`id-v2v/relight`): $0.20 / second of output 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
- [Bernini-R Edit Video](https://doitong.com/developers/models/bernini-r/edit-video.md) (`bernini-r/edit-video`): from $0.04 / second of output video
- [Bernini-R Reference Edit Video](https://doitong.com/developers/models/bernini-r/reference-edit-video.md) (`bernini-r/reference-edit-video`): from $0.04 / second of output video
- [DWPose Pose Prediction · Video](https://doitong.com/developers/models/dwpose/video.md) (`dwpose/video`): $0.0006 / second of processing time
- [Editto](https://doitong.com/developers/models/editto.md) (`editto`): from $0.04 / second of output video

## Links

- HTML page: https://doitong.com/developers/models/id-v2v
- 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=id-v2v
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/id-v2v