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

# Guia de integração da API Flux Videos

> Flux API guide - Ace Data Cloud

A API Flux Videos usa `POST /flux/videos` para concluir a geração de vídeo, geração de vídeo a partir de imagens de quadros-chave, extensão de vídeo e aprimoramento de rascunho. `action=generate` (padrão), `mode` seleciona o modo de geração; a consulta de resultados usa uniformemente o já existente `POST /flux/tasks`.

> Atualmente em Beta. A geração de vídeo a partir de texto, geração de vídeo a partir de imagem, extensão de vídeo e aprimoramento de rascunho estão disponíveis. O HTTP 200 e o ID da tarefa apenas indicam que a tarefa foi aceita; é necessário continuar consultando o resultado final.

## 1. Obter o Token da API

1. Registre-se ou faça login no [Console Ace Data Cloud](https://platform.acedata.cloud/console/applications), crie uma aplicação e obtenha o Token da API. Um Token da API universal pode chamar os serviços da plataforma; confirme que a aplicação possui permissão para chamar o serviço Flux e saldo disponível.
2. Consulte os planos e os preços de cada operação na [página do serviço Flux](https://platform.acedata.cloud/services/flux?tab=pricing). Quando o saldo for insuficiente, recarregue na [página de saldo do console](https://platform.acedata.cloud/console/coin).
3. As solicitações usam `Authorization: Bearer <seu Token>`. O Token deve ser armazenado em variáveis de ambiente do servidor; não o inclua em páginas de frontend, repositórios públicos, capturas de tela ou URLs de callback.

![Solicitar API Token no console](https://cdn.acedata.cloud/dvc3cg.jpg)

O código deste documento lê uniformemente a variável de ambiente:

```bash theme={null}
export ACEDATACLOUD_API_TOKEN='替换为你自己的 API Token'
```

| Item | Valor |
| - | - |
| Endereço raiz da API | `https://api.acedata.cloud` |
| Enviar tarefa de vídeo | `POST /flux/videos` |
| Consultar tarefa existente | `POST /flux/tasks` |
| Autenticação | `Authorization: Bearer $ACEDATACLOUD_API_TOKEN` |
| Formato da solicitação | `Content-Type: application/json` |

Para os campos completos e testes online, consulte [Flux Videos API](https://platform.acedata.cloud/documents/flux-videos); para consulta de tarefas, consulte [Flux Tasks API](https://platform.acedata.cloud/documents/flux-tasks)。

## 2. Selecionar a operação e a entrada

| action | mode | Entrada | Resultado |
| - | - | - | - |
| `generate`（valor padrão quando action é omitido） | `t2v` | `prompt` | Gerar vídeo a partir de texto |
| `generate` | `i2v` | `prompt`、`keyframes` | Gerar vídeo a partir de um ou mais quadros-chave |
| `generate` | `v2v` | `prompt`、`start_video` | Estender com base no vídeo de entrada |
| `generate` | `draft_enhance` | `draft_task_id` do rascunho que você já concluiu | Aprimorar esse rascunho |

O modelo de geração é `flux-3`, e `action` é `generate` (padrão). Selecione geração de vídeo a partir de texto, geração de vídeo a partir de imagem, extensão de vídeo ou aprimoramento de rascunho por meio de `mode`.

### Parâmetros gerais de geração

| Parâmetro | Descrição |
| - | - |
| `mode` | Obrigatório; `t2v`, `i2v`, `v2v` ou `draft_enhance` |
| `prompt` | Obrigatório para geração normal; o aprimoramento de rascunho não permite substituir o prompt original |
| `duration` | Para t2v/i2v, inteiro de 5–20 segundos; para v2v, inteiro de 5–15 segundos; ou `auto`; a duração final da saída pode ter uma pequena diferença em relação ao valor solicitado |
| `resolution` | `hd`, `fhd`, `qhd`, `uhd`; o padrão para geração normal é `hd`, e para aprimoramento de rascunho é `fhd` |
| `aspect_ratio` | `auto`, `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `9:21` |
| `draft` | Se deve gerar primeiro um rascunho; rascunhos suportam apenas `hd` |
| `generate_audio` | Se deve gerar áudio sincronizado; `false` é um valor válido, mantenha o valor booleano explícito |
| `safety_tolerance` | Opcional; inteiro de 0–4 |
| `async` | Recomendado definir como `true`, retornar imediatamente o ID da tarefa da plataforma e então consultar o resultado |
| `callback_url` | Opcional; endereço HTTP(S) para receber o resultado JSON final; após ser definido, também será aceito de forma assíncrona |

As URLs dos materiais devem poder ser acessadas pelo serviço. Se usar URLs temporárias assinadas, reserve tempo de validade suficiente para o download e o processamento. Não use endereços de páginas web como endereços de arquivos de imagem ou vídeo.

## 3. Vídeo a partir de texto: solicitação completa testada e resultado

A solicitação a seguir foi executada com sucesso na interface de produção antes do ajuste de preço em 2026-10-02. A omissão de `action` validou o comportamento de geração padrão; `async=true` evita aguardar por muito tempo a conexão HTTP.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/flux/videos' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light, steady camera, no text.",
    "duration": 5,
    "resolution": "hd",
    "draft": true,
    "async": true
  }'
```

Resposta de aceitação (ID de tarefa real):

```json theme={null}
{
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607"
}
```

Salve o `task_id` da sua própria resposta e continue consultando; não use o ID de tarefa do exemplo da documentação para consultar resultados de outras contas.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/flux/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"action":"retrieve","id":"替换为本次返回的 task_id"}'
```

O campo `response` retornado pela consulta de tarefa contém o resultado final do negócio. A seguir está o `response` obtido com sucesso neste teste, omitindo os metadados externos da tarefa. A URL do vídeo na documentação foi substituída por uma cópia do mesmo arquivo em uma CDN de exemplo de longa duração (SHA-256 idêntico); a chamada real retornará a URL de resultado própria desta tarefa:

```json theme={null}
{
  "success": true,
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607",
  "data": [
    {
      "id": "4341eb66-3845-4972-bb86-712a6cfae845",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/4341eb66-3845-4972-bb86-712a6cfae845-5f4391e1942c.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24,
      "draft_task_id": "4341eb66-3845-4972-bb86-712a6cfae845"
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": true
  },
  "cost": {
    "amount": 2.6884689277500002,
    "currency": "credit",
    "list_amount": 2.9871876975000005
  }
}
```

[Ver o vídeo testado desta vez](https://cdn.acedata.cloud/assets/examples/flux/4341eb66-3845-4972-bb86-712a6cfae845-5f4391e1942c.mp4)。A inspeção de mídia confirmou que a saída é um MP4 de 1280×704, 24 fps e 5,041667 segundos, com tamanho de arquivo de 2.607.276 bytes.

| Campo de resposta | Uso |
| - | - |
| `success` | Se a tarefa final foi bem-sucedida; o task\_id retornado na fase de aceitação não equivale a success=true |
| `task_id` | ID da tarefa da plataforma, usado para polling e processamento de idempotência de negócios |
| `trace_id` | Fornecido à equipe de suporte durante a investigação de problemas |
| `data[].video_url` | Endereço do resultado do vídeo que pode ser acessado |
| `data[].seconds/width/height/fps` | Duração, dimensões e taxa de quadros reais da saída medidas pelo servidor |
| `data[].draft_task_id` | ID de entrada para aprimoramento de rascunho; aparece somente quando um rascunho reutilizável é retornado |
| `usage` | Uso final faturado; não substitua os seconds reais pelo duration da solicitação |
| `cost.amount` | Credits efetivamente cobrados desta vez; `currency=credit` não é dólar americano |
| `cost.list_amount` | Credits antes do desconto de consumo aplicado ao usuário; retornado quando aplicável |

Este é um teste histórico de antes do ajuste de preço: `list_amount=2.9871876975` Credits, a conta tinha na época um desconto de consumo de 10%, e o `amount` real foi de 2.68846892775 Credits. O novo preço em 2026-10-02 foi reduzido em aproximadamente 6,33%; o mesmo rascunho de 5,041667 segundos, ao preço atual, custa 2.798125185 Credits (antes do desconto de consumo), ou 2.5183126665 Credits se ainda houver um desconto de consumo de 10%. As faturas de tarefas históricas não são recalculadas. Os planos e descontos de outras contas podem ser diferentes; este não é um preço fixo em dólares para todos os usuários.

## 4. Imagem para vídeo: normal e com quadros-chave temporizados

A seguir estão exemplos de parâmetros; é necessário substituir as URLs dos materiais, e isto não é uma declaração de que o exemplo já foi executado com sucesso. Após a geração ser concluída, consulte seguindo o processo acima; a estrutura do resultado é a mesma.

Para uma ou duas imagens, use um array normal:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "The camera slowly moves around the product in soft studio light.",
  "keyframes": [
    "https://example.com/first-frame.jpg"
  ],
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}
```

Ao especificar o momento dos quadros-chave, use pares de `[segundos, URL da imagem]`:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "A smooth transition from morning light to a warm sunset.",
  "keyframes": [[0, "https://example.com/start.jpg"], [5, "https://example.com/end.jpg"]],
  "duration": 5,
  "resolution": "hd",
  "async": true
}
```

São permitidos de 1 a 10 quadros-chave. O array com tempo deve estar em ordem crescente de tempo, o tempo deve ser de 0 a 20 segundos, e não é permitido misturar URLs normais com itens com tempo. Três ou mais quadros-chave normais devem especificar explicitamente duration; não é possível usar auto.

### Saída testada de imagem para vídeo

A entrada correspondente deste teste é a seguinte (somente o texto explicativo substitui o base64 completo; os demais campos são solicitações reais):

```json theme={null}
{
  "async": true,
  "action": "generate",
  "model": "flux-3",
  "prompt": "The toy sailboat drifts slowly across calm water. A steady camera, gentle daylight, no people or text.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "draft": false,
  "mode": "i2v",
  "keyframes": [
    "<下图 PNG 文件的原始 base64 字符串>"
  ]
}
```

![Quadro-chave de referência para a imagem para vídeo deste teste](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-input-b0525db595d2.png)

Após [baixar este quadro-chave PNG](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-input-b0525db595d2.png), é possível usar `base64.b64encode(image_bytes).decode("ascii")` do Python para obter a string original e colocá-la no array keyframes. Não use o texto explicativo no documento como entrada de imagem.

A seguir está a response final real de uma tarefa de produção de 2026-10-01 (não uma resposta simulada); somente a URL do vídeo foi substituída por uma cópia de exemplo de longo prazo com o mesmo hash. A entrada testada usou a string base64 original de um PNG de 1280×720 como quadro-chave único; a entrada de URL acima é um exemplo de parâmetro independente.

```json theme={null}
{
  "success": true,
  "task_id": "b1106de8-d586-4e23-b489-381e2f86a10f",
  "trace_id": "f62d5c56-cfb2-4f8f-b339-ef019d4c0d10",
  "data": [
    {
      "id": "b1106de8-d586-4e23-b489-381e2f86a10f",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-bef14458cc9d.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "i2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}
```

[Ver vídeo de teste](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-bef14458cc9d.mp4)。

## 5. Continuação de vídeo

`start_video` recebe o endereço de um arquivo de vídeo existente, `mode=v2v`, com duração máxima de 15 segundos.

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "prompt": "Continue the sailboat drifting forward with the same steady camera.",
  "start_video": "https://example.com/source.mp4",
  "duration": 5,
  "resolution": "hd",
  "async": true
}
```

### Saída de teste da continuação de vídeo

A entrada completa deste teste é a seguinte; ao reproduzir o aprimoramento de rascunho, substitua pelo seu próprio ID de rascunho. A URL do material usa uma cópia de exemplo de longo prazo do mesmo arquivo:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "start_video": "https://cdn.acedata.cloud/assets/examples/flux/b41293be-94c0-4dc7-9f39-ce04f0a8798d-c055a3079059.mp4",
  "prompt": "Continue the same sailboat drifting gently across calm water in the same continuous steady shot.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}
```

A seguir está a response final real da tarefa de produção de 2026-10-01 (não é uma resposta simulada); apenas a URL do vídeo foi substituída por uma cópia de exemplo de longo prazo com o mesmo hash.

```json theme={null}
{
  "success": true,
  "task_id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
  "trace_id": "4fb49afc-abca-4039-bbaa-adb66e293544",
  "data": [
    {
      "id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/8af9aa42-7e4d-47a4-bd61-144d97440c91-a512d6574811.mp4",
      "seconds": 5,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5,
    "output_mp_seconds": 4.296875,
    "mode": "v2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 18.219375,
    "currency": "credit",
    "list_amount": 20.24375
  }
}
```

[Ver vídeo de teste](https://cdn.acedata.cloud/assets/examples/flux/8af9aa42-7e4d-47a4-bd61-144d97440c91-a512d6574811.mp4)。

O `start_video` de entrada do teste é o [vídeo de rascunho concluído](https://cdn.acedata.cloud/assets/examples/flux/b41293be-94c0-4dc7-9f39-ce04f0a8798d-c055a3079059.mp4), e os demais parâmetros são duration=5, resolution=hd, generate\_audio=false.

## 6. Primeiro rascunho, depois aprimoramento

1. Use `draft=true`, `resolution=hd` para gerar um rascunho e aguarde a conclusão bem-sucedida.
2. Obtenha o ID de rascunho da plataforma a partir de `data[0].draft_task_id` final.
3. Use as credenciais do aplicativo da mesma propriedade para enviar a solicitação de aprimoramento:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "替换为自己的已完成草稿 ID",
  "resolution": "fhd",
  "async": true
}
```

O aprimoramento de rascunho não pode receber `prompt`, `duration`, `aspect_ratio`, `version`, `generate_audio`, `draft`, `keyframes`, `start_video` para substituir o conteúdo original. O cache de rascunho é um recurso temporário; faça o aprimoramento em tempo hábil; não há garantia de armazenamento permanente ou de um número fixo de dias de retenção. Rascunhos que não sejam seus/não sejam do aplicativo atual, rascunhos não concluídos e caches expirados não podem ser reutilizados. O rascunho e o aprimoramento são duas tarefas, e são cobrados separadamente após serem concluídos com sucesso.

### Saída de teste do aprimoramento de rascunho

A entrada completa deste teste é a seguinte; ao reproduzir o aprimoramento de rascunho, substitua pelo seu próprio ID de rascunho. A URL do material usa uma cópia de exemplo de longo prazo do mesmo arquivo:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "b41293be-94c0-4dc7-9f39-ce04f0a8798d",
  "resolution": "hd",
  "async": true
}
```

A seguir está a response final real da tarefa de produção de 2026-10-01 (não é uma resposta simulada); apenas a URL do vídeo foi substituída por uma cópia de exemplo de longo prazo com o mesmo hash.

```json theme={null}
{
  "success": true,
  "task_id": "1db6243b-4a05-4484-828c-25bb17de7108",
  "trace_id": "64f93fa1-8d18-4c8b-a6d2-888009eb7cfa",
  "data": [
    {
      "id": "1db6243b-4a05-4484-828c-25bb17de7108",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/1db6243b-4a05-4484-828c-25bb17de7108-058d92166607.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}
```

[Ver vídeo de teste](https://cdn.acedata.cloud/assets/examples/flux/1db6243b-4a05-4484-828c-25bb17de7108-058d92166607.mp4)。

A entrada de teste é o seu próprio draft\_task\_id=b41293be-94c0-4dc7-9f39-ce04f0a8798d, resolution=hd; o usage.mode final=t2v indica o modo de rascunho original. Esta tarefa e o rascunho original são cobrados separadamente.

## 7. Chamada Python de ponta a ponta

Instale `requests`, configure o seu próprio Token e execute o script abaixo para concluir “enviar uma vez → consultar periodicamente → gerar a URL do vídeo”. Tanto as consultas quanto as tentativas de repetição de rede devem usar o task\_id original, para evitar o reenvio de tarefas pagas.

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

base_url = "https://api.acedata.cloud"
headers = {
    "Authorization": "Bearer " + os.environ["ACEDATACLOUD_API_TOKEN"],
    "Accept": "application/json",
}
payload = {
    "action": "generate",
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light.",
    "duration": 5,
    "resolution": "hd",
    "draft": True,
    "async": True,
}
submitted = requests.post(base_url + "/flux/videos", json=payload, headers=headers, timeout=120)
submitted.raise_for_status()
accepted = submitted.json()
if accepted.get("error"):
    raise RuntimeError(accepted["error"])
task_id = accepted["task_id"]
print("Task ID:", task_id)  # 持久化保存，用于恢复轮询

# 30 分钟是本示例的客户端等待上限，不是服务的完成时限承诺。
deadline = time.monotonic() + 30 * 60
while time.monotonic() < deadline:
    polled = requests.post(
        base_url + "/flux/tasks",
        json={"action": "retrieve", "id": task_id},
        headers=headers,
        timeout=30,
    )
    polled.raise_for_status()
    task = polled.json()
    if task.get("error"):
        raise RuntimeError(task["error"])
    result = task.get("response") or task.get("result")
    if isinstance(result, dict) and result.get("success") is True:
        print("Video:", result["data"][0]["video_url"])
        print("Usage:", result.get("usage"))
        print("Cost:", result.get("cost"))
        break
    if isinstance(result, dict) and result.get("error"):
        raise RuntimeError(result["error"])
    time.sleep(10)
else:
    raise TimeoutError("Still processing; resume polling with task_id=" + task_id)
```

Após um timeout de rede, não trate um estado desconhecido como falha e reenvie imediatamente. Se `task_id` já tiver sido obtido, continue consultando essa tarefa; registre `task_id` e `trace_id` para facilitar a investigação. A própria interface de consulta não cobra taxas de geração.

## 8. Uso de callback

Adicione `callback_url` ao enviar; após a conclusão da tarefa, será feito POST do resultado JSON final para esse endereço. A estrutura de sucesso é consistente com o response mencionado anteriormente; em caso de falha, inclui error.

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "t2v",
  "prompt": "A small sailboat on calm water.",
  "duration": 5,
  "resolution": "hd",
  "draft": true,
  "callback_url": "https://your-server.example/flux-callback"
}
```

O endereço de callback deve ser acessível pela internet pública. Após receber a notificação, processe de forma idempotente com base em task\_id e retorne 2xx o mais rápido possível; o processamento de negócio pode ser enfileirado. Este documento não declara que o callback possui autenticação por assinatura: antes de operações sensíveis, como conceder benefícios de negócio, use seu próprio Token para consultar a mesma tarefa e verificar o resultado. Se o callback não for recebido, também é possível continuar a consulta; não gere novamente.

## 9. Cobrança atual e tabela de preços

Atualizado em 2026-10-02: os preços unitários de cada faixa desta interface de vídeo foram reduzidos em aproximadamente 6,33%; o método de medição, os pacotes e as regras de desconto por consumo permanecem inalterados. O cost nos responses de medições históricas mencionados anteriormente é a cobrança no momento da conclusão da tarefa e não representa a cotação atual.

A geração de vídeo é cobrada por **segundos reais de saída**. Abaixo estão os preços unitários atuais em Credits sem a aplicação de descontos por consumo da conta, consistentes com as regras da [página de preços do Flux](https://platform.acedata.cloud/services/flux?tab=pricing).

| Operação/modo | Resolução | Preço unitário em Credits |
| - | - | -: |
| rascunho t2v / i2v | hd | 0.555 / segundo |
| rascunho v2v | hd | 1.11 / segundo |
| aprimoramento de rascunho t2v / i2v / correspondente | hd | 1.5725 / segundo |
| igual ao acima | fhd | 2.6825 / segundo |
| igual ao acima | qhd | 3.7 / segundo |
| igual ao acima | uhd | 7.4 / segundo |
| aprimoramento de rascunho v2v / correspondente | hd | 3.7925 / segundo |
| igual ao acima | fhd | 4.9025 / segundo |
| igual ao acima | qhd | 6.0125 / segundo |
| igual ao acima | uhd | 8.7875 / segundo |

Conversão para dólares americanos: `custo real（USD）= cost.amount（Credits）× preço do pacote / amount do pacote`. As faixas de recarga e os descontos por consumo afetam o preço real; Credits não podem ser tratados diretamente como USD. Tarefas com falha não cobram taxas de geração; o valor final prevalece conforme o resultado concluído e os registros de chamadas no console.

## 10. Perguntas frequentes e solução de problemas

| Situação | Sugestão |
| - | - |
| Erro de parâmetro（400） | Verifique action=generate, mode, duration e o formato dos quadros-chave; não misture campos de diferentes modos de geração |
| Erro de autenticação（401） | Verifique o Bearer Token, as permissões do aplicativo e se as credenciais são válidas |
| Rejeição pela moderação de conteúdo（403） | Ajuste o material e o prompt; não envie repetidamente sem alterações |
| Limitação de taxa（429） | Reduza a concorrência e tente novamente com backoff |
| service\_unavailable（503） | A operação atual não está disponível; tarefas assíncronas já aceitas podem relatar esse erro no response final |
| task\_id já foi retornado, mas ainda não há vídeo | Continue consultando o response; não trate HTTP 200 como geração concluída |
| O rascunho não pode ser reutilizado | Confirme o próprio usuário/aplicativo atual, que a tarefa foi concluída, que a solicitação original tinha draft=true, e verifique se o cache temporário ainda é válido |

Ao fornecer feedback, inclua task\_id, trace\_id, horário da solicitação e parâmetros mascarados; não envie o API Token. Para mais formas, consulte o [guia de integração Flux MCP](https://platform.acedata.cloud/documents/flux-mcp).


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