aisplice

Referência da API

Tarefas assíncronas

Trabalhos de imagem, vídeo e música compartilham um mesmo ciclo de vida durável: envie uma vez, persista o task_id, observe um estado final e depois busque o resultado. Construa um único executor de tarefas e escolha apenas a família de endpoints por modelo.

#Um único ciclo de vida para todos os modelos assíncronos

  1. 1

    Envie uma vez

    Use uma Idempotency-Key única e salve a resposta imediatamente.

    POST /v1/{capability}
  2. 2

    Persista o task_id

    Armazene-o antes de o worker confirmar o trabalho.

    task_id
  3. 3

    Consulte ou receba o webhook

    Compare o status sem diferenciar maiúsculas e minúsculas e pare em um estado final.

    GET /{task_id}
  4. 4

    Busque e persista o resultado

    Chame /content após o sucesso e armazene a URL da plataforma retornada.

    GET /{task_id}/content

#Famílias de endpoints

RecursoEnviarConsultarConteúdo
Imagem/v1/images/tasks/v1/images/tasks/{task_id}/v1/images/tasks/{task_id}/content
Vídeo/v1/videos/v1/videos/{task_id}/v1/videos/{task_id}/content
Música/v1/music/generations/v1/music/tasks/{task_id}/v1/music/tasks/{task_id}/content

#Valores de status

Um ciclo de vida, dois vocabulários de API. Tarefas de imagem, música e 3D usam os termos de tarefa da OpenAI; vídeos e todos os payloads de webhook usam os termos de vídeo da OpenAI. Uma verificação de status escrita para uma família nunca bate na outra, sem avisar — esta tabela é o mapeamento.

Ciclo de vidaImagem · música · 3DVídeo · webhookFinalSignificado
NOT_STARTprocessingqueuednãoAceita pelo gateway, ainda não entregue a um canal.
SUBMITTEDqueuedqueuednãoEnviada ao upstream e confirmada pelo provedor.
QUEUEDqueuedqueuednãoAguardando na fila do provedor.
IN_PROGRESSprocessingin_progressnãoRenderizando. progress traz uma string de porcentagem, como "60%".
SUCCESSsucceededcompletedsimConcluída. Busque o resultado em /content.
FAILUREfailedfailedsimFalhou definitivamente. fail_reason explica o motivo; a cota reservada é reembolsada.
UNKNOWNunknownunknownnãoO provedor parou de informar um estado que o gateway consegue mapear. Continue consultando com um prazo limite e depois faça a conciliação — não trate como sucesso nem como falha.

Verifique o conjunto de estados finais, nunca “não está em execução”

Trate succeeded / completed e failed como os únicos pontos de parada, e todo o resto — inclusive um termo que esta tabela não lista — como ainda em execução. Novos estados intermediários podem aparecer; novos estados finais seriam uma mudança incompatível e não vão aparecer.

UNKNOWN não é falha

Uma tarefa pode ficar em UNKNOWN quando o provedor para de informar um estado que o gateway consegue mapear. Consulte-a com um prazo limite e escale para uma pessoa ou para um job de conciliação — tratá-la como falha cobra duas vezes pela nova tentativa; tratá-la como sucesso entrega um resultado vazio.

#Loop de consulta seguro

Pare nos termos finais da família que você está consultando, mantenha um prazo de tempo real para todo o resto e use backoff para que uma tarefa travada não vire um loop intenso.

poll.py
import time, requests

# The two vocabularies. Pick the one that matches the endpoint you poll.
TASK_DONE, TASK_FAILED = {"succeeded"}, {"failed"}      # images / music / 3D
VIDEO_DONE, VIDEO_FAILED = {"completed"}, {"failed"}    # videos + webhooks
DEADLINE_SECONDS = 15 * 60

def wait_for_image_task(task_id, api_key):
    started = time.monotonic()
    delay = 2
    while True:
        response = requests.get(
            f"https://www.aisplice.store/v1/images/tasks/{task_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()
        status = task.get("status", "")

        if status in TASK_DONE:
            return task
        if status in TASK_FAILED:
            raise RuntimeError((task.get("error") or {}).get("message", "task failed"))

        # queued / processing / unknown all mean "not finished". Wait — but
        # never forever: hand an overdue task to reconciliation.
        if time.monotonic() - started > DEADLINE_SECONDS:
            raise TimeoutError(f"task {task_id} still {status} after the deadline")

        time.sleep(delay)
        delay = min(delay * 1.5, 15)

Retome após reinicializações

Persista o task_id, a família de endpoints, o modelo, o horário de criação e o seu próprio identificador de negócio. Um worker reiniciado consegue continuar consultando sem enviar e pagar uma segunda tarefa.

#Retenção dos resultados

Busque /content somente após o sucesso. Persista a URL da plataforma retornada no seu registro de negócio e baixe uma cópia privada quando os seus requisitos de retenção exigirem armazenamento independente.

Ainda com problemas?

Envie para nós o ID da requisição ou a mensagem de erro e vamos investigar.

AnteriorConceitos básicos de integraçãoPróximoEvite cobranças duplicadas