API reference

Introduction

Base URLs, authentication, request conventions, and error responses. Review Diffio API behavior, response fields, setup details, and production workflows.

Use this reference to plan Diffio API requests and responses. All endpoints use JSON over HTTPS at https://api.diffio.ai/v1.

API reference essentials

1
Base URL
Use the production base URL for all API requests.
https://api.diffio.ai/v1
Append the endpoint path to the base URL when calling the REST API directly.
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
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 uploadUrl and uploadMethod. Use the returned method and set Content-Type to match contentType.
- Download URLs from get_generation_download are signed and expire after about two hours.
4
Error responses
Errors return JSON with an error message. Some errors include additional fields such as code or billing metadata.
Example error response
{ "error": "Payment failed. Update your payment method in the billing portal.", "code": "paymentFailed"}
Billing holds return 402Payment required, billing issue such as paymentFailed. API usage can be blocked until billing is updated. with code paymentFailed. API usage can be blocked until billing is updated. Spend limit errors use spendLimitExceeded.
5
Rate limits
Rate limits and spend limits depend on your plan and API key settings. Review the API pricing page for current limits and use the developer dashboard to monitor usage.