Handleidingen

Snelstart

Maak een asynchrone taak aan en verwerk polling, voltooiing, fouten en callbacks.

RunAPI gebruikt Tasks voor asynchrone generatie van afbeeldingen, video, audio en muziek. Een aanmaakverzok keert snel terug; uw applicatie peilt vervolgens de Task of ontvangt de callback-events die vermeld staan in de API-referentie van het betreffende eindpunt.

Een taak aanmaken

Kies een model en een eindpunt in de catalogus en stuur de vereiste invoergegevens van het eindpunt. Dit voorbeeld start een Flux 2-tekst-naar-afbeelding-taak:

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'

Een geaccepteerd asynchroon verzoek retourneert 202 Accepted met een taakidentificatie:

JSON

{
  "id": "task_id",
  "status": "processing"
}

Sla id op in uw applicatierecord. Het is de stabiele identificator die wordt gebruikt voor polling, ondersteuning en callback-reconciliatie.

Dubbele taakaanmaak voorkomen

Eindpunten voor het aanmaken van taken accepteren een optionele Idempotency-Key-header met een ondoorzichtige waarde van maximaal 512 tekens. Genereer één waarde per logische taak en bewaar deze bij het verzoek totdat u weet of het is geaccepteerd.

Als een time-out of verbindingsfout het resultaat onbekend laat, herhaal dan exact hetzelfde Task-aanmaakverzoek met dezelfde sleutel. RunAPI retourneert de oorspronkelijke Task in plaats van een tweede aan te maken en daarvoor kosten in rekening te brengen. Het hergebruiken van een sleutel met een ander Task-aanmaakverzoek retourneert 409 Conflict. Genereer een nieuwe sleutel voor een opzettelijk nieuwe Task en gebruik X-Client-Request-Id niet als deze sleutel.

Een onderbroken synchroon verzoek herstellen

Trage synchrone eindpunten houden de verbinding normaal open en retourneren dezelfde terminale respons als voorheen. Er zijn geen wijzigingen in polling vereist voor bestaande integraties.

Voor een bewust kortere verbindingsbudget stuurt u Prefer: wait=N. Als de taak na dat expliciete budget nog actief is, geeft RunAPI 202 Accepted terug met dezelfde taak-id, een ondoorzichtige Location-URL voor herstel en Retry-After voor de aanbevolen queryvertraging. Volg Location exact in plaats van zelf een resultaat-URL samen te stellen. Een voltooid taakresultaat behoudt de terminale HTTP-status, toegestane headers, het inhoudstype en de body; decodeer response.body volgens response.content_type, dat niet altijd JSON is.

Een taak pollen

Voeg de taakidentificatie toe aan hetzelfde eindpuntpad:

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ga door zolang status processing is. Gebruik begrensde backoff tussen verzoeken in plaats van continu te pollen. Een taak wordt definitief wanneer de status completed of failed is.

Voltooiing afhandelen

Een completed-respons bevat de taak-id, de terminale status en de eindpuntspecifieke resultaatvelden. Sla het benodigde resultaat op en stop met pollen. Raadpleeg de API-referentie van het eindpunt voor de exacte resultaatstructuur in plaats van aan te nemen dat elk media-eindpunt dezelfde velden retourneert.

Mislukking afhandelen

Een failed-respons bevat de taak-id, de terminale status en een door RunAPI opgestelde error indien beschikbaar. Stop met pollen, registreer de identificatie en de fout, en probeer het opnieuw alleen wanneer uw applicatie de fout als tijdelijk heeft geclassificeerd. Bij een nieuwe poging wordt een nieuwe taakidentificatie aangemaakt.

Een callback ontvangen

Voeg een openbare HTTPS-callback_url toe aan het aanmaakverzoek wanneer u wilt dat RunAPI de callback-gebeurtenissen verstuurt die voor dat eindpunt zijn gedocumenteerd:

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

Elke callback-body komt overeen met één levenscyclusgebeurtenis in de API- Referentie van het eindpunt en laat polling-only-factureringsdetails weg. Terminale callbacks bevatten dezelfde resultatenvelden als terminale polling-responsen; sommige eindpunten versturen ook gedocumenteerde processing-callbacks. Stuur snel een geslaagde HTTP-respons terug en houd polling beschikbaar voor afstemming wanneer bezorging vertraagd is of uw callback-handler niet beschikbaar is.

Lees Callbacks om een Callback Secret aan te maken, handtekeningen te verifiëren en nieuwe pogingen veilig af te handelen.