Introduction

API reference essentials

1. 1

   Base URL

   Use the production base URL for all API requests.

   https://api.diffio.ai/v1Copy

   Append the endpoint path to the base URL when calling the REST API directly.

2. 2

   Authentication

   Send the API key on every request using one of the supported headers.

   • Authorization: Bearer <apiKey>
   • X-Api-Key: <apiKey>
   • Xi-Api-Key: <apiKey>

   Use API keys with read and write permissions that match the endpoint.

3. 3

   Request conventions

   • All /v1 endpoints use POST with JSON bodies.
   • OPTIONS is accepted for CORS preflight.
   • Send Content-Type: application/json for JSON payloads.
   • Request fields use camelCase, for example apiProjectId.
   • create_project returns an upload session. Send the file to upload.edgeBaseUrl in parts with Authorization: Bearer {upload.uploadToken}, then call complete_project_upload. The official SDKs do this for you.
   • Download URLs from get_generation_download are Diffio media URLs that expire after six hours.
   • Only diffio-4.5-flash and diffio-4.5-pro are available. Endpoints for older models answer 410 with code model_retired.
4. 4

   Error responses

   Errors return JSON with an error message. Some errors include additional fields such as code or billing metadata.

   Example error response

   Copy

   {  "error": "Payment failed. Update your payment method in the billing portal.",  "code": "paymentFailed"}

   Billing blocks return 402Payment required, billing issue such as paymentFailed. API usage can be blocked until billing is updated.. The code needsPaymentMethod means the $5 starter credit is used up, or cannot cover this file, and no payment method is saved. When the refusal comes from a check of your remaining credit, the response also includes estimatedCostCents and remainingCreditCents; once the account is blocked, later requests return only error and code, so treat both fields as optional. paymentFailed means a charge failed. New generations are refused until a payment method is added on the Billing page. A generation created before its upload was processed is checked again when it starts, and fails with the error needsPaymentMethod if the credit cannot cover the file.

5. 5

   Rate limits

   Rate limits depend on your plan. Review the API pricing page for current limits and use the developer dashboard to monitor usage.

Endpoints

Use these endpoints to create projects, run generations, manage keys, read usage, and configure webhooks.