> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sora2 Запрос статуса персонажа

> Запрос статуса задачи создания персонажа и результатов

> [!NOTE]
>
> **Для пользователей из материкового Китая:** используйте `https://toapis.cn` в качестве эндпоинта (Base URL). Замените `https://toapis.com` на `https://toapis.cn` во всех примерах этого документа.

## Обзор

Запрос статуса и результата задач создания персонажей. Получение подробной информации о созданных персонажах (ID персонажа, отображаемое имя, имя пользователя и т.д.) для использования в последующей генерации видео.

> [!NOTE]
>
> **Примечания:**
>
> * Создание персонажа — асинхронная задача, требуется периодический опрос этого API
> * После завершения задачи возвращаются детали персонажа
> * `username` персонажа можно использовать в промптах в формате `@username`
> * ID задачи персонажа можно использовать через параметр `character_url` в генерации видео

## Параметры пути

**task\_id** `string` *required*

ID задачи создания персонажа

Это ID задачи, возвращённый из API [Создание персонажа](https://docs.toapis.com/docs/ru/api-reference/videos/sora2/create-persona.md)

Пример: `"task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"`

## Аутентификация

**Authorization** `string` *required*

Bearer Token аутентификация

```
Authorization: Bearer YOUR_API_KEY
```

Получите API Key на [странице управления API ключами](https://toapis.com/console/token)

## Поля ответа

**id** `string`

Уникальный идентификатор задачи (ID задачи создания персонажа)

**object** `string`

Тип объекта, всегда `generation.task`

**model** `string`

Используемая модель

**status** `string`

Статус задачи:

* `queued` — в очереди
* `in_progress` — выполняется
* `completed` — успешно завершено
* `failed` — ошибка

**progress** `integer`

Прогресс выполнения (0-100)

**created\_at** `integer`

Время создания задачи (Unix timestamp)

**completed\_at** `integer`

Время завершения задачи (Unix timestamp, только после завершения)

**expires\_at** `integer`

Время истечения результата (Unix timestamp, только после завершения)

**result** `object`

Результат задачи (только когда status = completed)

`result.type` = `character`, а `result.data.characters` содержит список персонажей

**error** `object`

Ошибка (только когда status = failed)

```bash cURL theme={null}
curl --request GET \
  --url 'https://toapis.com/v1/characters_tasks/task_01KBZ0TZZ7C7M3WS1TJM0PH8J4' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

```python Python theme={null}
import requests
import time

def query_character_task(task_id):
    """Запрос статуса задачи создания персонажа"""
    url = f"https://toapis.com/v1/characters_tasks/{task_id}"
    headers = {"Authorization": "Bearer YOUR_API_KEY"}
    
    response = requests.get(url, headers=headers)
    return response.json()

def wait_for_character(task_id, max_wait=300, interval=5):
    """Ожидание завершения создания персонажа"""
    start_time = time.time()
    
    while time.time() - start_time < max_wait:
        result = query_character_task(task_id)

        status = result['status']
        progress = result.get('progress', 0)
        print(f"Статус: {status}, Прогресс: {progress}%")
        
        if status == 'completed':
            characters = result['result']['data']['characters']
            for char in characters:
                print(f"ID персонажа: {char['id']}")
                print(f"Отображаемое имя: {char['display_name']}")
                print(f"Имя пользователя: {char['username']}")
            return result
        
        if status == 'failed':
            raise Exception("Ошибка создания персонажа")
        
        time.sleep(interval)
    
    raise Exception("Таймаут ожидания")

# Пример использования
task_id = "task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"
result = wait_for_character(task_id)
```

```javascript JavaScript theme={null}
async function queryCharacterTask(taskId) {
  const response = await fetch(
    `https://toapis.com/v1/characters_tasks/${taskId}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  return await response.json();
}

async function waitForCharacter(taskId, maxWait = 300000, interval = 5000) {
  const startTime = Date.now();
  
  while (Date.now() - startTime < maxWait) {
    const result = await queryCharacterTask(taskId);

    const { status, progress } = result;
    console.log(`Статус: ${status}, Прогресс: ${progress}%`);
    
    if (status === 'completed') {
      const characters = result.result.data.characters;
      characters.forEach(char => {
        console.log(`ID персонажа: ${char.id}`);
        console.log(`Отображаемое имя: ${char.display_name}`);
        console.log(`Имя пользователя: ${char.username}`);
      });
      return result;
    }
    
    if (status === 'failed') {
      throw new Error('Ошибка создания персонажа');
    }
    
    await new Promise(resolve => setTimeout(resolve, interval));
  }
  
  throw new Error('Таймаут ожидания');
}

// Пример использования
const taskId = 'task_01KBZ0TZZ7C7M3WS1TJM0PH8J4';
waitForCharacter(taskId).then(result => console.log(result));
```

```go Go theme={null}
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

type CharacterResponse struct {
    ID        string `json:"id"`
    Object    string `json:"object"`
    Model     string `json:"model"`
    Status    string `json:"status"`
    Progress  int    `json:"progress"`
    CreatedAt int64  `json:"created_at"`
    Result    struct {
        Type string `json:"type"`
        Data struct {
            Characters []struct {
                ID                string `json:"id"`
                DisplayName       string `json:"display_name"`
                ProfilePictureURL string `json:"profile_picture_url"`
                Username          string `json:"username"`
            } `json:"characters"`
        } `json:"data"`
    } `json:"result"`
}

func queryCharacterTask(taskID string) (*CharacterResponse, error) {
    url := "https://toapis.com/v1/characters_tasks/" + taskID
    
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    
    var result CharacterResponse
    json.Unmarshal(body, &result)
    return &result, nil
}

func main() {
    taskID := "task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"
    
    for i := 0; i < 60; i++ {
        result, err := queryCharacterTask(taskID)
        if err != nil {
            panic(err)
        }
        
        fmt.Printf("Статус: %s, Прогресс: %d%%\n", result.Status, result.Progress)
        
        if result.Status == "completed" {
            for _, char := range result.Result.Data.Characters {
                fmt.Printf("ID персонажа: %s\n", char.ID)
                fmt.Printf("Отображаемое имя: %s\n", char.DisplayName)
                fmt.Printf("Имя пользователя: %s\n", char.Username)
            }
            break
        }
        
        time.Sleep(5 * time.Second)
    }
}
```

```json 200 (В процессе) theme={null}
{
  "id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1765251461,
  "metadata": {}
}
```

```json 200 (Завершено) theme={null}
{
  "id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "completed",
  "progress": 100,
  "created_at": 1765251461,
  "completed_at": 1765251507,
  "result": {
    "type": "character",
    "data": {
      "characters": [
        {
          "id": "ch_6937998961208191a45ef08447a554df",
          "display_name": "Turbo Whiskers",
          "profile_picture_url": "https://upload.toapis.com/f/image/character_task_xxx.jpg",
          "username": "duksvfkf.turbo_whis"
        }
      ]
    }
  },
  "metadata": {}
}
```

```json 400 (Неверный запрос) theme={null}
{
  "error": {
    "code": 400,
    "message": "Неверные параметры запроса",
    "type": "invalid_request_error"
  }
}
```

```json 401 (Ошибка аутентификации) theme={null}
{
  "error": {
    "code": 401,
    "message": "Ошибка аутентификации, проверьте ваш API ключ",
    "type": "authentication_error"
  }
}
```

```json 404 (Задача не найдена) theme={null}
{
  "error": {
    "code": 404,
    "message": "Задача не найдена",
    "type": "not_found_error"
  }
}
```

```json 429 (Ограничение частоты) theme={null}
{
  "error": {
    "code": 429,
    "message": "Слишком много запросов, попробуйте позже",
    "type": "rate_limit_error"
  }
}
```

## Использование персонажа в генерации видео

После завершения создания персонажа вы можете использовать его в генерации видео. Есть два способа ссылки:

### Способ 1: Использование @username в промпте

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sora-2",
    "prompt": "@duksvfkf.turbo_whis is dancing in the rain"
  }'
```

### Способ 2: Использование параметра character\_url

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sora-2",
    "prompt": "A cute cat is dancing in the rain",
    "character_url": "task_01KC0JZCMTMQ70D68XTM56Q5D0"
  }'
```

> [!TIP]
>
> **Совет:** `username` получается из поля `characters[].username` в результатах запроса, `character_url` использует `task_id` задачи создания персонажа.

## Рекомендации по опросу

| Параметр | Рекомендуемое значение |
| - | - |
| Интервал опроса | 5 секунд |
| Максимальное время ожидания | 5 минут |
| Обработка таймаута | Повторная отправка задачи или обращение в поддержку |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.